New Webhooks – Documo

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.

The event name in headers will be in the following format: x-webhook-event

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.complete - when a fax has been completed, it'll show as successful or failed
fax.v1.outbound.init - an outbound fax has been created but not yet transmitted (future feature)
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.outbound.complete - when a fax has been completed, it'll show as successful or failed
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
idp.v1.document-type.updated - updates the document type in IDP

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
}

Related articles