Webhooks

Webhooks contain "multi-part/form-data" content that includes both data and files.

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.

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 "Advanced Fax Routing" 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. Note that webhooks on a number level will only allow for fax.inbound as faxes are sent from users and not numbers with our system.

How to set on the number level:

https://share.getcloudapp.com/JruDmGgX

How to set on the account level:

https://share.getcloudapp.com/8Luo6po6

Note: The fax.outbound.extended will post each status to your provided URL, as opposed to fax.outbound which will only post success/failure. Valid fax statuses include: success, transmitting, scheduled, failed, processing, and cancelled.

Processing means the fax was submitted (to us), transmitting means it has been sent to our server, scheduled means you have scheduled your fax, success means the fax was successful, and cancelled means the fax was cancelled.

Below are examples of the data that will post to your endpoint provided for both fax.inbound and fax.outbound events:

fax.inbound:

{"resultInfo":"OK","messageId":"d7afa15d-a79-b013-18ec9c846ef3","channelType":"web","isArchived":false,"isFilePurged":false,"deliveryId":"2210514133330175","watermark":"2210514133425960493","messageNumber":"1436823","status":"success","pagesCount":1,"pagesComplete":1,"duration":22000,"faxNumber":"+18332394039","faxCsid":"702432","faxCallerId":"702422","faxECM":256,"faxSpeed":14400,"faxDetected":true,"faxProtocol":17,"faxAttempt":1,"direction":"inbound","errorCode":"0","resultCode":"0","country":"US","resolvedDate":"2021-05-14T13:34:00.000Z","createdAt":"2021-05-14T13:34:30.000Z","accountId":"efaa36f7-d9a0-43aa-0cb1114eea0c","processingStatusName":"success","classificationLabel":"inbound","recipientName":null,"subject":null,"deviceId":null,"faxbridgeId":null,"deletedAt":null,"account":{"uuid":"efaa36f7-d9a0-493f-a3aa-0cb1114eea0c","accountNumber":"1201734191","accountName":"Documo","accountType":"master"},"cf":{}}

fax.outbound:


{"resultInfo":"OK","messageId":"3bdc40b9-0c0f-b054-8ddbdb94ec1e","deliveryId":"2210516330095","watermark":"221051515860254","messageNumber":"143725907","status":"success","pagesCount":1,"pagesComplete":1,"duration":38000,"faxNumber":"+18582850","faxCsid":"T.Co - Documo","faxCallerId":"858250","faxECM":256,"faxSpeed":33600,"faxDetected":true,"faxProtocol":34,"faxAttempt":1,"direction":"outbound","channelType":"email","recipientName":"18582io","subject":"Test fax","deviceId":null,"faxbridgeId":null,"accountId":"efaa36f7-d9af-a3aa-0cb1114eea0c","errorCode":"0","resultCode":"0","isArchived":false,"isFilePurged":false,"country":"US","createdAt":"2021-05-14T16:43:59.000Z","resolvedDate":"2021-05-14T16:45:12.000Z","deletedAt":null,"account_id":"efaa36f7-d9a0a3aa-0cb1114eea0c","device_id":null,"faxbridge_id":null,"processingStatusName":"success","classificationLabel":"outbound","account":{"uuid":"efaa36f7-d9a0-493f-a3aa-0cb1114eea0c","accountNumber":"1201191","accountName":"Documo","accountType":"master"},"cf":{}}

Webhook Receiving Example

Under node.js it is recommended to use "multer" package from npm. This will handle form data that we are sending and will convert it to a readable format.

See: https://www.npmjs.com/package/multer

Example: 

const router = require('express').Router();
const multer = require('multer');
const httpAuth = require('http-auth');
const upload = multer({dest: 'uploads/'});

// 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',
    upload.single('attachment'),
    auth.check(function (req, res) {

        // Webhook data
        console.log(JSON.parse(req.body.data));

        // Webhook attachment.
        console.log(req.file);

        res.sendStatus(200);
    }));

module.exports = router;
Did this answer your question?