Webhooks allow you to get updates 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. HTTP webhooks are multipart/form-data POST requests, and should be processed like form submissions.
Depending on the type of webhook, you can configure the callback URLs in a few ways:
Incoming fax notification:
Fax completed notification:
callbackUrl property in the request body when you send a fax via the /faxes endpoint.The Sinch servers expect a 200 HTTP result response from your server within 60 seconds of sending the webhook event, otherwise the webhook event will count as failed.
If a webhook fails, we will automatically retry sending the fax up to 16 times. There will be a back off before each retry, which increases as follows:
| Retry number | Back off |
|---|---|
| 1 | 5 minutes |
| 2 | 10 minutes |
| 3 | 20 minutes |
| 4 | 30 minutes |
| 5-16 | 6 hours |
The different types of events are:
The different events that can trigger a webhook
The different events that can trigger a webhook
| Enum Value | Description |
|---|---|
| INCOMING_FAX | A webhook event triggered by an fax is incoming. |
| FAX_COMPLETED | A webhook event triggered by a fax that has successfully completed. |
"INCOMING_FAX"This webhook is triggered when a fax is received on a Sinch number associated with a service. The webhook will contain information about the fax, such as the sender, the recipient, and the content of the fax. You set the callback URL for incoming fax events on the service, either through the dashboard or using the service API.
Multipart/form-data request payloads are encoded as forms with a content type of JSON and the actual fax content as a 'file' application/pdf attachment.
Application/json request payloads are a JSON object with the file encoded as a base64 string as part of the JSON object.
Returns a 200 OK response if the webhook was received successfully.
{ "event": "INCOMING_FAX", "eventTime": "2021-11-01T23:25:67Z", "fax": { "id": "01HDFHACK1YN7CCDYRA6ZRMA8Z", "direction": "INBOUND", "from": "+14155552222", "to": "+14155553333", "numberOfPages": 1, "status": "COMPLETED", "price": { "amount": "0.00", "currencyCode": "USD" }, "createTime": "2021-11-01T23:25:67Z", "completedTime": "2021-11-01T23:25:67Z", "projectId": "YOUR_PROJECT_ID", "serviceId": "YOUR_SERVICE_ID" }, "file": "{application/pdf}" }
Triggered when the fax has been completed. The callback will contain information about the fax, such as the sender, the recipient, and the content of the fax. You must set the callback URL where you want the callback sent when you make a send fax request.
| event | string Default: "FAX_COMPLETED" Always fax completed for this event.
| ||||||
| file | string <binary> <binary> <application/pdf> The fax content as pdf attachment to the body | ||||||
| eventTime | string <date-time> Time of the event. | ||||||
object (Fax) |
Returns a 200 OK response if the webhook was received successfully.
{ "event": "FAX_COMPLETED", "eventTime": "2021-11-01T23:25:67Z", "fax": { "id": "01HDFHACK1YN7CCDYRA6ZRMA8Z", "direction": "INBOUND", "from": "+14155552222", "to": "+14155553333", "numberOfPages": 1, "status": "COMPLETED", "price": { "amount": "0.07", "currencyCode": "USD" }, "createTime": "2021-11-01T23:25:67Z", "completedTime": "2021-11-01T23:25:67Z", "callbackUrl": "https://www.my-website.com/callback", "callbackUrlContentType": "multipart/form-data", "imageConversionMethod": "HALFTONE", "projectId": "YOUR_PROJECT_ID", "serviceId": "YOUR_SERVICE_ID" }, "file": "{application/pdf}" }