Webhooks API reference

What is a webhook destination?

A URL of yours, an event filter and a secret. POST /v1/webhooks registers one. The body needs the url and can carry a description and event_types. An empty or missing list means every event type.

The answer carries the secret once. Every delivery to this URL is signed with it. The webhooks guide has the three headers and code that verifies the signature in Python and TypeScript.

How do I change or pause a destination?

PATCH /v1/webhooks/{webhook_id} changes the URL, the description and the filter. It also takes status, which pauses a destination and resumes it. A paused destination gets no deliveries. DELETE /v1/webhooks/{webhook_id} removes it. GET /v1/webhooks lists the destinations of the environment, without their secrets.

How is a secret rotated?

POST /v1/webhooks/{webhook_id}/rotate-secret returns a new secret. The summary states the overlap: the old one signs too for 24 hours. During that time each delivery carries two signatures, and a receiver that accepts either keeps working. previous_secret_expires_at on the destination says when the overlap ends.

So a rotation needs no window of downtime. Rotate, deploy the new secret to the receiver, and the old one stops signing by itself.

How do I test a receiver?

POST /v1/webhooks/{webhook_id}/test sends a signed webhook.test event to the destination and answers 202 with the event it sent. The receiver sees a real delivery with a real signature, and no fax is involved. Use it right after registering, and again after each rotation.

Where do I see what was delivered?

GET /v1/webhook-deliveries lists the delivery attempts. Each row has the event id and type, the attempt number, the status the receiver answered and the duration. It also has an error when there was one, and when the next attempt is due. The summary adds "no payload secrets". The list filters by webhook_id and by event_id, and pages with cursor and limit.

A receiver that answers outside the 2xx range gets the event again on a fixed schedule. The guide has the schedule with its date.

What does a replay do?

POST /v1/webhook-deliveries/{delivery_id}/replay sends the event of that delivery again and answers 202. The event id is the same as the first time. A handler that deduplicates on the id treats a replay of something it already handled as a no-op, and handles one it missed.

For a longer gap, the log in the events group returns every event in order, delivered or not.

Which scope do webhook calls need?

One: webhook:admin, for every operation in the group, the lists included. The default API key does not carry it. A call with it answers 403 scope_missing. Choose the scope when you create the key that registers webhooks.

An agent key is never issued webhook:admin. Where events go is decided by a person or by a key of the organization, not by the agent whose faxes they describe.

Do test and live events mix?

No. A destination belongs to the environment of the credential that registered it. A test key's destination gets the events of sandbox faxes, and a live key's destination gets the events of real ones.

curl https://api.faxforagents.com/v1/webhook-deliveries \
  -H "Authorization: Bearer ffa_test_..."

curl https://api.faxforagents.com/v1/webhook-deliveries/DELIVERY_ID/replay \
  -X POST \
  -H "Authorization: Bearer ffa_test_..."

curl https://api.faxforagents.com/v1/webhooks \
  -H "Authorization: Bearer ffa_test_..."

curl https://api.faxforagents.com/v1/webhooks \
  -X POST \
  -H "Authorization: Bearer ffa_test_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/webhooks/fax"}'

curl https://api.faxforagents.com/v1/webhooks/WEBHOOK_ID \
  -X DELETE \
  -H "Authorization: Bearer ffa_test_..."

curl https://api.faxforagents.com/v1/webhooks/WEBHOOK_ID \
  -X PATCH \
  -H "Authorization: Bearer ffa_test_..." \
  -H "Content-Type: application/json" \
  -d '{}'

curl https://api.faxforagents.com/v1/webhooks/WEBHOOK_ID/rotate-secret \
  -X POST \
  -H "Authorization: Bearer ffa_test_..."

curl https://api.faxforagents.com/v1/webhooks/WEBHOOK_ID/test \
  -X POST \
  -H "Authorization: Bearer ffa_test_..."