Webhooks

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. 

 

Below you will find what each of these webhook events mean:

Valid fax statuses:

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
}

Common Errors

Unable to get local issuer certificate: This is not a Documo issue. The error comes from your web server. The server sends only the site certificate and does not send the GoDaddy intermediate certificate. Our webhook client does standard TLS validation. Without the intermediate certificate it cannot build a trusted chain to the GoDaddy root, so the connection fails.

Fix on your side:

Install the GoDaddy intermediate bundle on the web server. GoDaddy includes it in the certificate download as gd_bundle-g2-g1.crt or a similar name.

• Apache: set SSLCertificateChainFile to the bundle, or append the bundle to the certificate file. Restart Apache.

• Nginx: append the bundle to the end of the certificate file that ssl_certificate points to. Reload Nginx.

• IIS: import the bundle into the "Intermediate Certification Authorities" store. Restart IIS.

• Load balancer or hosting provider: upload the bundle in the certificate chain field of the provider console.

To verify: run "curl -v <https://<webhook-url>>" from outside your network, or scan the host at SSL Server Test (Powered by Qualys SSL Labs) When the chain shows as complete, the Documo webhook test succeeds.

If you have any other questions, please reach out to support@documo.com.