Webhooks contain multipart-form/data.
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 whitelisting: 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. 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.
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;