Skip to content

Webhooks

This page shows provider‑specific webhook endpoints, sample payloads, and signature verification examples.

Outbound Status — Phaxio

  • Endpoint: POST /phaxio-callback?job_id=<faxbot_job_id>
  • Signature: header X-Phaxio-Signature (HMAC‑SHA256 of the raw body using PHAXIO_API_SECRET)

Example form payload (Phaxio): 

fax[id]=123456&fax[status]=success&fax[num_pages]=2

Verification (Python): 

import hmac, hashlib
secret = PHAXIO_API_SECRET.encode()
digest = hmac.new(secret, raw_body_bytes, hashlib.sha256).hexdigest()
assert hmac.compare_digest(digest, header_value.strip().lower())

Inbound — Phaxio

  • Endpoint: POST /phaxio-inbound
  • Signature: header X-Phaxio-Signature (HMAC‑SHA256)

Example JSON payload: 

{
  "fax": {
    "id": 98765,
    "from": "+15551230000",
    "to": "+15559870000",
    "num_pages": 3,
    "status": "received",
    "file_url": "https://files.phaxio.com/..."
  }
}

Verification (Python): same HMAC pattern as above on the raw request body.

Inbound — Sinch Fax API v3

  • Endpoint: POST /sinch-inbound
  • Basic auth (optional): set SINCH_INBOUND_BASIC_USER/PASS
  • HMAC (optional): header X-Sinch-Signature with secret SINCH_INBOUND_HMAC_SECRET

Example JSON payload (simplified): 

{
  "id": "abcd-1234",
  "from": "+15551230000",
  "to": "+15559870000",
  "num_pages": 2,
  "status": "received",
  "file_url": "https://fax.api.sinch.com/v3/..."
}

HMAC verification (Python): 

import hmac, hashlib
secret = SINCH_INBOUND_HMAC_SECRET.encode()
digest = hmac.new(secret, raw_body_bytes, hashlib.sha256).hexdigest()
assert hmac.compare_digest(digest, header_value.strip().lower())

Inbound — SIP/Asterisk (Self‑Hosted)

  • Endpoint: POST /_internal/asterisk/inbound
  • Header: X-Internal-Secret: <ASTERISK_INBOUND_SECRET>
  • Body (JSON): 
    {
  "tiff_path": "/faxdata/in.tiff",
  "to_number": "+15559870000",
  "from_number": "+15551230000",
  "faxstatus": "received",
  "faxpages": 2,
  "uniqueid": "1603261234.89"
}

Example curl (internal network): 

curl -X POST -H 'X-Internal-Secret: <secret>' -H 'Content-Type: application/json' \
  http://api:8080/_internal/asterisk/inbound \
  -d '{"tiff_path":"/faxdata/in.tiff","to_number":"+1555..."}'

Security Tips

  • Use HTTPS for all public callbacks.
  • Keep secrets out of logs; audit only metadata (job ids, event types).
  • Rotate webhook secrets periodically and validate signatures strictly.