Fax Webhooks — Get Notified the Moment a Fax Finishes

How it works

When a fax changes state, the Telnyx event reaches us first; we then look at which of your endpoints subscribed to that event type and queue a delivery for each one. The delivery worker signs the JSON body with your endpoint's secret using HMAC-SHA256 and sends it in an X-SFM-Signature header shaped t=<timestamp>,v1=<signature>. The signed string is the header's timestamp, a literal dot, then the raw body (t.body) — your handler recomputes HMAC-SHA256 over that exact string and compares to v1; a match proves authenticity and the timestamp lets you reject stale replays. Delivery is at-least-once: a non-2xx response is retried with exponential backoff across several attempts before the event is parked in a dead-letter, so a brief outage on your side does not lose the notification.

What you can do

• ✓Subscribe to fax.delivered, fax.failed, and fax.received events per endpoint
• ✓Receive a signed JSON POST the moment a fax reaches a final state
• ✓Verify authenticity with the HMAC-SHA256 X-SFM-Signature header and your secret
• ✓Reject replays using the timestamp carried inside the signature header
• ✓Rely on at-least-once delivery with exponential-backoff retries and a dead-letter
• ✓Register multiple endpoints, each with its own event set and signing secret

Setup steps

1. 1Confirm Business or Enterprise — the webhook endpoint form is hidden on lower plans
2. 2Stand up an HTTPS URL that accepts POST; it must be publicly reachable and not an internal address
3. 3At /dashboard/developers, add the endpoint, choose the events, and save the signing secret shown once
4. 4In your handler, read the raw body and the X-SFM-Signature header before parsing JSON
5. 5Recompute HMAC-SHA256 over the signed string — the header's t value, a literal dot, then the exact raw body (t.body) — with your secret and compare to the v1 value
6. 6Return a 2xx quickly; do the real work asynchronously so retries are not triggered by a slow handler

Example

POST https://your-app.example.com/hooks/fax
X-SFM-Signature: t=1893456000,v1=9f86d0818...hmac...
Content-Type: application/json

{
  "event": "fax.delivered",
  "fax": {
    "id": "65b1...",
    "to": "+15551234567",
    "status": "delivered",
    "pages": 3
  }
}

Fax Webhooks — FAQ