Skip to main content

Receiving Webhooks for Programmable Fax

When you send a Programmable Fax command and receive a successful response (i.e. 200 OK), you can expect to receive a webhook. The webhook will be delivered to the primary URL specified on the Application associated with the call. If that URL does not resolve, or your application returns a non 200 OK response, the webhook will be delivered to the failover URL, if one has been specified.

In order to minimize webhook delivery time, Telnyx:

  • does not enforce the order in which webhooks are delivered
  • retries webhook delivery if your application does not respond within a certain time threshold.

As a result, you may encounter:

  • out-of-order webhooks
  • simultaneous (or near simultaneous) webhooks
  • duplicate webhooks

Duplicate webhooks may cause your application to issue duplicate commands. You can instruct Telnyx to ignore duplicate commands by sending a command_id parameter as part of your commands. Commands with duplicate command_ids within 60 seconds will be ignored.

Example: Receiving a webhook from an outbound fax

When you place an outbound fax, you will receive a number of webhooks indicating the current status of the fax. The first webhook you will receive will have A queued status indicating that Telnyx successfully received the request to send the fax.

"data": {
"event_type": "fax.queued",
"id": "3691d047-d22a-424d-80ed-fe871981aa6d",
"occurred_at": "2020-04-22T19:32:12.538002Z",
"record_type": "event",
"payload": {
"call_duration_secs": 50,
"connection_id": "7267xxxxxxxxxxxxxx",
"direction": "outbound",
"fax_id": "b679398e-8b4c-46bd-8630-6797f1ab5228",
"from": "+35319605860",
"original_media_url": "",
"partial_content": true,
"status": "queued",
"to": "+13129457420",
"user_id": "a5b1dfa3-fd2e-4e02-8ea4-xxxxxxxxxxxx"
"meta": {
"attempt": 1,
"delivered_to": ""
record_typeDescription of the record.
idunique id for the webhook
event_typeThe type of event
occurred_atISO-8601 datetime of when event occured
toDestination number or SIP URI of the call
fromNumber or SIP URI placing the call
fax_idUnique ID for the Programmable Fax
client_stateConfigurable state to track commands
statusCan be one of queued, media.processed, sending.started, delivered, failed

Example: Receiving a webhook on successful fax delivery

"event_type": "fax.delivered",
"id": "3320554f-6b74-4138-a74b-a1e2ec7eaf8b",
"occurred_at": "2022-01-07T10:01:43.677850Z",
"payload": {
"call_duration_secs": 79,
"connection_id": "1232154810234",
"direction": "outbound",
"fax_id": "c62be5bc-9b13-4b6c-abda-34dd8b541287",
"from": "+19459457421",
"original_media_url": "",
"page_count": 1,
"status": "delivered",
"to": "+13129457420",
"user_id": "bdaa1f9f-1018-4156-867d-6c4ac9f556eb"

Example: Receiving a webhook on failed fax delivery

"event_type": "fax.failed",
"id": "d906ecda-db21-428e-9ca0-74dae7e7c144",
"occurred_at": "2022-01-05T22:23:46.888808Z",
"payload": {
"connection_id": "1232154810234",
"direction": "outbound",
"failure_reason": "user_busy",
"fax_id": "f7b303ed-674c-4962-951b-848380510893",
"from": "+19459457421",
"original_media_url": "",
"status": "failed",
"to": "+13129457420",
"user_id": "417b0cc2-39e0-4ab9-b116-e56543649aa9"

Possible failure reasons

Inspect the failure_reason field in webhook's payload to debug failed deliveries of your faxes. The possible failure reasons are:

  • account_disabled
  • connection_channel_limit_exceeded
  • destination_invalid
  • destination_not_in_countries_whitelist
  • destination_not_in_service_plan
  • destination_unreachable
  • fax_signaling_error
  • invalid_ecm_response_from_receiver
  • no_outbound_profile
  • outbound_profile_channel_limit_exceeded
  • outbound_profile_daily_spend_limit_exceeded
  • receiver_call_dropped
  • receiver_communication_error
  • receiver_decline
  • receiver_incompatible_destination
  • receiver_invalid_number_format
  • receiver_no_answer
  • receiver_no_response
  • receiver_recovery_on_timer_expire
  • receiver_unallocated_number
  • service_unavailable
  • user_busy
  • user_channel_limit_exceeded

On this page