Phaxio

Webhooks

Webhooks allow Phaxio to update you in real-time about the status of your faxes. Webhooks are triggered by events such as the completion of a fax, and transmit information about the state of that fax to you via HTTP(S) or email.

Specifying Webhook URLs

The first thing we need to send you a webhook is a destination URL. This should be a valid URI with a http, https, or mailto scheme that points to a destination that you control. Examples of valid webhook URLs are http://example.com/phaxio_webhook and mailto:alice@example.com.

There are three places where you can specify URLs:

  1. For sent and received faxes, you can set global webhook URLs on your webhook settings page. These apply to all faxes unless superceded by a more specific URL.
  2. For received faxes, you can specify webhook URLs for particular numbers in your account on the phone numbers page.
  3. For sent faxes, you can specify a webhook URL using the callback_url parameter in your send fax request.

Specifying a Webhook Version

Webhooks are versioned to match the API, and you can update your webhook version on the webhook settings page. This document applies to v2.1 webhooks.

Enabling Inflight Webhooks

Currently, Phaxio supports two categories of webhooks: postflight and inflight. Postflight webhooks are triggered when a fax completes, regardless of success. Inflight webhooks are triggered by events during the transmission of a fax, such as the transfer of individual pages.

Inflight webhooks are disabled by default, but can be enabled on the webhook settings page.

Webhook Formats

Email webhooks are normal HTML emails containing information about the fax. HTTP webhooks are multipart/form-data POST requests, and should be processed like form submissions. See the documentation for send fax webhooks and receive fax webhooks for more specific information.

Webhook Verification

On the webhook settings page, you can generate a webhook token. If present, Phaxio will use this token to generate a signature for the request. In your application, you can then verify the request using the token, as documented on the Verifying Webhook Requests page.

Retries

If a webhook fails, we will automatically retry up to 16 times. There will be a backoff before each retry, which increases as follows:

Retry No. Backoff
1 5 minutes
2 10 minutes
3 20 minutes
4 30 minutes
5-16 6 hours