Webhooks contain JSON object.
All API documentation on webhooks can be found here: https://docs.documo.com/#create-webhook
Note: The server should respond with any 2** status so that we can then consider the webhook successful. If we receive any other status (i.e. 500 or 4**), the webhook will be rescheduled a total of seven times.
IP for Trusted IP List: 35.225.187.84
Webhook Retry Schedule
There will be seven attempts made prior to a failure. This schedule is as follows: 5s, 25s, 2m, 10m, 52m, 4h, 22h.
After that, you will receive an email notification with an error and webhook data. If the webhook has an attachment, it will not be included in the email.
To create webhooks, first click the Toolbox, then click Webhooks:
Next, click Add New Webhook:
Webhook Basic Auth
We recommended that your webhook URLs be protected using basic authentication. To use basic authentication, toggle 'Use Basic Auth' switcher in the webhook settings, seen here:
NOTE: The username and password will be converted to Base64 string and will be sent in an "authorization" header alongside each request.
You can set webhooks up on a number or an account level.
x-webhook-event
Below you will find what each of these webhook events mean:
| Event | What happens when event is triggered |
|---|---|
| fax.v1.inbound.init | An inbound fax has been created but not yet transmitted |
| fax.v1.inbound.page | When each page of an inbound fax has been received |
| fax.v1.inbound.succeed | An inbound fax was successful |
| fax.v1.inbound.failed | An inbound fax failed |
| fax.v1.inbound.complete | When a fax has completed, it'll show as successful or failed |
| fax.v1.outbound.init | An outbound fax has been created but not yet transmitted |
| fax.v1.outbound.succeed | When an outbound fax was successful |
| fax.v1.outbound.failed | When an outbound fax has failed |
| fax.v1.outbound.complete | When a fax has completed, it'll show as successful or failed |
| fax.v1.number.add | When a number is added to an account |
| fax.v1.number.release | When a number is released from an account |
| fax.v1.number.ported | When a number has been ported to an account |
| identity.v1.user.create | When a user is created |
| identity.v1.user.delete | When a user is deleted |
| identity.v1.session.initiated | When a user signs into the app |
| identity.v1.session.terminated | When a user signs out of the app |
| ocr.v1.document.complete | A document has been processed with OCR |
| ocr.v1.ocr-to-pdf.complete | When an OCR to PDF document is ready to view |
| idp.v1.document-type.updated | When the document type is updated |
| idp.v1.document-field-value.assigned | When the document fields are extracted and assigned |
| idp.v1.split-detection.completed | When split detection has completed |
| dsm.v1.outbound.succeeded | When an outbound message has succeeded |
| dsm.v1.outbound.failed | When an outbound message has failed |
| dsm.v1.inbound.succeeded | When an inbound message has succeeded |
Valid fax statuses:
| Fax Status | Definition |
|---|---|
| Scheduled | Fax has been scheduled for future delivery |
| Processing | Fax queued for delivery |
| Transmitting | Fax delivery in process |
| Success | Fax delivery was successful |
| Failed | Fax delivery failed |
| Cancelled | Fax delivery cancelled |
Please note that you will not receive fax attachments with these webhooks. Instead, use the API download endpoint to download attachments.
Below is an example request for webhooks:
const router = require('express').Router();
const httpAuth = require('http-auth');
// Basic auth check
const auth = httpAuth.basic({}, (username, password, cb) => {
// It is recommended to store username and password in environment variables
cb(username === 'username' && password === 'password');
});
router.post('/webhook',
auth.check(function (req, res) {
// Webhook data
console.log(req.body);
res.sendStatus(200);
}));
module.exports = router;
Below is an example of the data that will post to your endpoint:
{
"messageId": "532749c8-4e7c-401c-a847-8534ce4e9906",
"messageNumber": "11111111111",
"status": "transmitting",
"pagesComplete": 1,
"pagesCount": 5,
"duration": 140000,
"faxNumber": "+12349999999",
"faxCsid": "Fax CSID",
"faxCallerId": "1234567890",
"faxECM": 256,
"faxSpeed": 33600,
"faxDetected": true,
"faxProtocol": 0,
"faxAttempt": 1,
"direction": "inbound",
"channelType": "web",
"deviceId": "e82cf4cb2557ec0de3ecb4cb4f488665fd764596b5a19d1c3e35aa9756af1168",
"faxbridgeId": null,
"accountId": "fccc209e-da90-4952-88c6-28bf1561f479",
"errorInfo": "",
"errorCode": "0",
"resultCode": "0",
"resultInfo": "",
"isArchived": false,
"isFilePurged": false,
"country": "US",
"createdAt": "2023-11-28T17:36:27.753Z",
"resolvedDate": "2023-11-28",
"cf": {},
"deletedAt": null
}