CrazyFax webhooks
CrazyFax webhooks let your own systems know the moment a fax is sent, fails, or arrives. For example, you can mark an invoice as "faxed" in your accounting system, or pull new inbound faxes straight into a document management tool.
Where to set it up
- Go to Products > CrazyFax > Fax Settings.
- On the General tab, choose the fax service you want and click Configure This Service.
- Open the Webhooks tab.
- Click Add Webhook.
- Fill in the form (see below) and click Add Webhook Endpoint.
You can add more than one webhook endpoint per fax service, for example one for your CRM and one for a team chat channel.
For a full technical reference, click How webhooks work on the Webhooks tab, or go to Products > CrazyFax > Webhooks.
Settings explained
| Setting | What it does |
|---|---|
| Fax Service | Which fax service sends events to this endpoint. |
| Endpoint Name | A friendly name so you can recognise the endpoint later, for example "Accounts CRM". Up to 128 characters. |
| Target URL | Where events are sent. Use an https:// address that is reachable from the public internet. |
| Webhook Signing Secret | A secret your server uses to confirm messages really came from CrazyFax. Click Generate to create a strong secret, then Copy to save it somewhere safe. |
| Route Filter | Only send events for one inbound route. Leave as All routes to receive events for every route on the service. |
| Content Type | Always application/json. |
| Enabled Events | Which events you want to receive (see below). |
| Timeout Seconds | How long CrazyFax waits for your server to reply. Leave blank to use the default of 10 seconds. |
| Max Delivery Retries | How many times CrazyFax tries to deliver an event before giving up. Leave blank to use the default of 10 attempts. |
| Endpoint Status | Turns delivery on or off. New endpoints start switched off, so remember to turn this on. Turning a webhook off does not change your billing or plan. |
After saving, the signing secret is not shown again. If you lose it, use the rotate secret button (key icon) next to the endpoint to create a new one, then update your server.
Events you can choose
| Event | Label in portal | When it is sent |
|---|---|---|
fax.v1.outbound.succeeded | Outbound succeeded | A fax you sent was delivered successfully. |
fax.v1.outbound.failed | Outbound failed | A fax you sent failed, was cancelled, or expired. |
fax.v1.inbound.documents_ready | Inbound documents ready | A fax was received and the document is ready for you. |
fax.v1.inbound.failed | Inbound failed | An incoming fax could not be received or processed. |
fax.v1.outbound.billing_hold | Outbound billing hold | A fax you sent is waiting because your account does not have enough credit yet. |
fax.v1.outbound.billing_hold_released | Outbound billing hold released | Credit is back and the waiting fax is being sent. |
fax.v1.outbound.billing_hold_expired | Outbound billing hold expired | The fax waited too long for credit and was not sent. |
fax.v1.inbound.billing_hold_released | Inbound billing hold released | Credit is back and a received fax that was on hold has been released to you. |
fax.v1.inbound.billing_hold_expired | Inbound billing hold expired | A received fax waited too long for credit and could not be released. |
A good starting set for most businesses is Outbound succeeded, Outbound failed and Inbound documents ready. The billing hold events are useful if you want to be warned when faxes are held up by low credit.
Sending to a chat app
If your Target URL is a Slack, Discord, Microsoft Teams or Google Chat incoming webhook address, CrazyFax sends a short, easy-to-read message instead of the full JSON.
Example message
{
"event": "fax.v1.outbound.succeeded",
"delivery_id": 1842,
"payload_version": "2026-04-30",
"account_code": "295327",
"fax": {
"id": "fax_01JZABCFAX123",
"direction": "outbound",
"status": "completed",
"from_number": "61290561899",
"to_number": "61255501001",
"customer_reference": "INV-10001",
"pages_total": 3,
"pages_transferred": 3,
"terminal_result_category": "success",
"terminal_result_text": "sent",
"completed_at": "2026-05-10T00:15:30Z",
"created_at": "2026-05-10T00:10:00Z",
"updated_at": "2026-05-10T00:15:30Z"
}
}| Field | What it means |
|---|---|
event | Which event this is. |
delivery_id | A unique ID for this delivery. Use it to ignore duplicates. |
payload_version | The message format version. |
fax.id | A unique ID for the fax. Use it to find or download the fax. |
fax.direction | outbound (you sent it) or inbound (you received it). |
fax.status | The fax's current status, for example completed. |
fax.from_number / fax.to_number | The sending and receiving fax numbers. |
fax.customer_reference | Your own reference, if you added one when sending, for example an invoice number. |
fax.pages_total / fax.pages_transferred | How many pages the fax has, and how many were successfully sent or received. |
fax.terminal_result_category / fax.terminal_result_text | The final result, for example success / sent or received. |
fax.completed_at / created_at / updated_at | When the fax finished, was created and was last updated (UTC). |
Inbound faxes use the same layout, with direction set to inbound.
Webhooks never include the fax image or PDF. To get the document, use the fax.id to find it under Fax Jobs in the portal, or through the CrazyFax API.
Security
Each request includes these headers:
Content-Type: application/json
X-Fax-Event: <event name>
X-Fax-Delivery-ID: <unique delivery ID>
X-Fax-Timestamp: <time the message was signed, for example 2026-05-10T00:15:30Z>
X-Fax-Signature: sha256=<signature>The CrazyFax signature is calculated over the timestamp (converted to Unix seconds) and the message body together. Reject messages where the timestamp is more than 5 minutes old. See Verifying webhook signatures.
Testing
Click the test button (paper plane icon) next to an endpoint. CrazyFax sends a signed fax.v1.webhook.test message to your URL and shows whether it was delivered, including the HTTP result from your server.
{
"event": "fax.v1.webhook.test",
"delivery_id": 99,
"payload_version": "2026-04-30",
"account_code": "295327",
"test": {
"endpoint_id": 12,
"message": "This is a signed webhook test event from Crazy Fax.",
"created_at": "2026-05-10T00:16:00Z"
}
}Delivery and retries
- Your server should reply with a
2xxstatus (for example200or204) within the endpoint timeout (10 seconds by default). Redirects, errors and timeouts count as failures. - If delivery fails, CrazyFax tries again after 5 minutes, 15 minutes, 1 hour, 4 hours, then every 12 hours, up to the endpoint's retry limit (10 attempts by default).
- Retries only repeat the notification. They never send the fax again.
- A failed webhook does not change the result of the fax.
Delivery history
Go to Products > CrazyFax > Delivery & Worker Logs and open the Webhook Deliveries tab. It shows each delivery with its event type, the related fax job, the number of attempts and whether it succeeded, is pending or failed. You can search and filter by status.
Email alerts and webhooks
CrazyFax email alerts (on the Alerts tab) and webhooks are independent. Turning one off does not turn the other off. Use email alerts if you want the fax emailed to a person, and webhooks if you want a system to be notified automatically.