Fax Status Webhooks — Signed Delivery Callbacks
Instead of polling every fax for its result, you register a webhook endpoint and let Send FAX Mail post the outcome to you. When a fax reaches a terminal state, we send a signed HTTP POST to your URL for fax.delivered, fax.failed, or fax.received. Each delivery carries an HMAC-SHA256 signature in an X-SFM-Signature header so you can verify it genuinely came from us. Delivery is at-least-once with exponential-backoff retries and a dead-letter, and you can retry a dead-lettered delivery by hand. Endpoints are managed at /dashboard/developers alongside your API keys.
Plan requirement
Outbound webhooks are part of the Business ($79.99/mo) and Enterprise ($169.99/mo) plans, the same gate as the REST API. Creating an endpoint is blocked on lower plans, and the delivery-log viewer and the Retry-now action are Business+ features; revoking or deleting an endpoint stays open on any plan so a downgraded account can clean up.
How it works
You register a URL, choose which events it should receive, and we store a per-endpoint signing secret. When a fax hits a terminal outcome, the Telnyx webhook fans the event out through our delivery queue, and a cron worker POSTs it to your URL with an X-SFM-Signature header. That signature is an HMAC-SHA256 over a signed string built from the header's timestamp, a dot, then the raw request body — so you recompute the same HMAC with your secret and compare before trusting the payload, which also blocks replay of an old body. The URL you register is checked by an SSRF guard so it cannot point at an internal address. If your endpoint is down, we retry with exponential backoff and finally dead-letter the delivery, which you can re-queue from the delivery log.
What you can do
- ✓Receive fax.delivered, fax.failed, and fax.received as signed HTTP POSTs
- ✓Verify each delivery with an HMAC-SHA256 X-SFM-Signature and a per-endpoint secret
- ✓Rely on at-least-once delivery with exponential-backoff retries and a dead-letter
- ✓Inspect a per-endpoint delivery log with status, attempts, and last response code
- ✓Re-queue a dead-lettered delivery with the Retry-now action
- ✓Register only SSRF-safe HTTPS URLs — internal addresses are refused
Setup steps
- 1Confirm the account is on Business or Enterprise so webhooks are active
- 2Open /dashboard/developers and add a webhook endpoint with a public HTTPS URL
- 3Choose the events to receive: fax.delivered, fax.failed, fax.received
- 4Copy the per-endpoint signing secret shown when you create it
- 5At your URL, recompute the HMAC over timestamp + '.' + raw body and compare to X-SFM-Signature
- 6Watch the delivery log, and use Retry-now to re-queue anything that dead-lettered
Example
POST https://yourapp.com/hooks/fax (delivered by us)
X-SFM-Signature: t=1710000000,v1=9f2b...hmac...
Content-Type: application/json
{
"event": "fax.delivered",
"fax": { "id": "fax_123", "to": "+15551234567", "status": "delivered", "pages": 3 }
}Fax Status Webhooks — FAQ
Each POST carries an X-SFM-Signature header. Build the signed string as the header's timestamp, a dot, then the exact raw request body, and compute an HMAC-SHA256 of it with your endpoint's signing secret. If your value matches the v1 part of the header, the delivery is authentic; if not, reject it. Using the raw body and the timestamp together also stops an attacker from replaying an old payload.
Delivery is at-least-once. If your URL errors or times out, we retry with exponential backoff over a series of attempts, and if it still cannot be delivered the event is dead-lettered rather than lost. You can see the failed delivery in the per-endpoint log and re-queue it with the Retry-now action once your endpoint is healthy again.
Three fax lifecycle events: fax.delivered when an outbound fax lands, fax.failed when it does not, and fax.received when an inbound fax arrives on one of your numbers. You pick the subset each endpoint should get when you register it, so a receive-only integration need not process delivery events.
It must be a public HTTPS URL. We run an SSRF guard on the URL you register so it cannot point at an internal or private address, which protects against a webhook being used to probe internal services. Make sure the endpoint is reachable from the public internet, or deliveries will fail and eventually dead-letter.
Build with the Fax Status Webhooks
API access and webhooks are included on the Business and Enterprise plans. Create a key at /dashboard/developers and start sending.
7-day free trial · No credit card required