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.
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.
Below you will find what each of these webhook events mean:
fax.v1.inbound.init - an inbound fax has been created but not yet transmitted (future feature)
fax.v1.inbound.page - when each page of an inbound fax has been received (future feature)
fax.v1.inbound.succeed - an inbound fax was successful
fax.v1.inbound.failed - an inbound fax failed
fax.v1.inbound.page - each time a new page has been received, an event is sent (future feature)
fax.v1.inbound.complete - when a fax has been completed, it'll show as successful or failed
fax.v1.inbound.failed - when an inbound fax has failed, an event is sent
fax.v1.outbound.init - an outbound fax has been created but not yet transmitted (future feature)
fax.v1.outbound.complete - when a fax has been completed, it'll show as successful or failed
fax.v1.outbound.succeed - when an outbound fax was successful, an event is sent
fax.v1.outbound.failed - when an outbound fax has failed, an event is sent
fax.v1.number.add - when a number is added
fax.v1.number.release - when a number is released
fax.v1.number.ported - when a number has been ported
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
sign.v1.document.complete - when a Signature document has been completed
sign.v1.document.failed - when a Signature document has failed
ocr.v1.document.complete - the document has been processed with OCR
ocr.v1.ocr-to-pdf.complete - when an OCR to PDF document is ready to view
Valid fax statuses include: scheduled, processing, transmitting, success, failed, and cancelled.
Scheduled - the fax has been scheduled for a future time
Processing - fax was submitted to us
Transmitting - it has been sent to our server
Success - the fax was successful
Failed - the fax failed
Cancelled - the fax was 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 }