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 authentication. Select between Basic Auth and OAuth 2.0:
Basic auth — Username and password are entered. Documo sends those as a standard HTTP Basic Authorization header on every webhook delivery.
OAuth 2.0 — Client ID, Client Secret, Token URL, and optional Scope are entered. Before delivering, Documo calls this token URL with a client_credentials grant, gets back a short-lived access token, and sends it as Authorization: Bearer on the webhook POST. The token is cached (encrypted) and reused until shortly before it expires.
NOTE: The username and password will be converted to Base64 string and will be sent in an "authorization" header alongside each request.
Webhooks can be set up on a number or an account level.
Below you will find what each of these webhook events mean:
| Event | What happens when event is triggered |
|---|---|
| fax.v1.inbound.init | An inbound fax has been created but not yet transmitted (number level) |
| fax.v1.inbound.page | When each page of an inbound fax has been received (number level) |
| fax.v1.inbound.complete | When a fax has completed, it'll show as successful or failed (number level) |
| fax.v1.outbound.init | An outbound fax has been created but not yet transmitted |
| fax.v1.outbound.succeed | When an outbound fax was successful |
| fax.v1.outbound.failed | When an outbound fax has failed |
| fax.v1.outbound.complete | When a fax has completed, it'll show as successful or failed |
| fax.v1.number.add | When a number is added to an account |
| fax.v1.number.release | When a number is released from an account |
| fax.v1.number.ported | When a number has been ported to an account |
| 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 |
| ocr.v1.document.complete | A 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 | When the document type is updated |
| idp.v1.document-field-value.assigned | When the document fields are extracted and assigned |
| idp.v1.split-detection.completed | When split detection has completed |
| idp.v1.document.created | When a document is added to a workspace |
| idp.v1.document.updated | When a document's properties changed |
| idp.v1.document.edited | When the file content was edited |
| idp.v1.document.viewed | When a document was opened |
| idp.v1.document-tags.updated | When a tag was attached or removed |
| idp.v1.document.moved | When a document moved between workspaces |
| idp.v1.document.split | When split/duplicate document produced a new document |
| idp.v1.document.ehr-uploaded | When the document was sent to an EHR |
| idp.v1.document.signed | When a signed version is attached to a document |
| idp.v1.classification.completed | When classification is finished running |
| idp.v1.extraction.completed | When extraction is finished running |
| idp.v1.document.shared | When a document is shared to an external guest |
| idp.v1.document-share.approved | When the shared document has been approved by guest |
| idp.v1.document-share.viewed | When a shared document has been viewed |
| idp.v1.document-share.retracted | When a shared document has been retracted |
| dsm.v1.outbound.succeeded | When an outbound message has succeeded |
| dsm.v1.outbound.failed | When an outbound message has failed |
| dsm.v1.inbound.succeeded | When an inbound message has succeeded |
| workflow.v1.run.initiated | When a workflow was triggered |
| workflow.v1.run.succeeded | When a workflow was successful |
| workflow.v1.run.failed | When a workflow failed |
Valid fax statuses:
| Fax Status | Definition |
|---|---|
| Scheduled | Fax has been scheduled for future delivery |
| Processing | Fax queued for delivery |
| Transmitting | Fax delivery in process |
| Success | Fax delivery was successful |
| Failed | Fax delivery failed |
| Cancelled | Fax delivery 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
}
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.