Configure and Use Webhooks in Docubee

• Webhooks Overview
• Configure Webhooks
• Add Webhooks to Your Workflows
• Secure Your Webhooks

A More Technical Look at Webhooks

What is a Webhook Payload?

Use Headers in Webhooks

Response JSON

{
     "timestamp":"2019-12-17T02:23:56+00:00",
     "wfVariables":{
          "accusoft_solutions_workflowInitiator":"test@test.com",
          "First_Name":"Joe",
          "accusoft_solutions_workflowInitiatorName":"Joe Test"
     }
}

Configure a Webhook

1. In Settings, select the Webhooks tab under Organization. 
2. Webhooks require a few configuration options before you can make use of them:
   • Webhook Name – A custom name that you give your webhook connection so that you are able to identify it when adding it to a workflow.
   • Webhook URL – The URL of the server that will receive the webhook POST requests. 
     • It must start with https:// or  http://
   • Optional Secret Token – Set a webhook secret to ensure that POST requests sent to the payload URL are from Docubee. When you set a secret, you’ll receive the ontask-signature header in the webhook POST request. See the section Secure Your Webhooks for more information.

Add Webhooks to Your Workflows

1. Open the add task selector, go to the Send & Save section and click Webhook. Note: Anyone who has permission to build workflows will be able to add webhook tasks.
2. After you add a webhook task, you will see a right-side panel with configuration options. Note: If you are an admin of this organization, you can go into your account settings and configure your webhook. If you do have at least one webhook connection already configured, you’re ready to move on to the next step. If you do not have any webhook connections configured yet, depending on your permissions, you may see a message that you need to contact an organization owner or administrator to configure a webhook.
3. In the Webhook Configuration tab, from the Select Connection dropdown menu, select the webhook connection to which you want to send the request.
   • Use the Suspend workflow branch if webhook fails toggle to choose whether or not to suspend a workflow on a webhook failure. Note: When we send the POST request to a webhook URL, Docubee will try to send the data up to 3 times before suspending the request. By default, if a failure occurs the workflow will still continue on to the next step. If you prefer the workflow to suspend instead and stop proceeding, turn the toggle on.
   • Turn on the Include document identifiers toggle to include document properties.
4. After configuring these options, you may add any other tasks to your workflow as needed before you publish and run it.

Secure a Webhook

Setting Your Secret Token

Validating Payloads from Docubee

const express = require('express');
const crypto = require('crypto');
const app = express();
const bodyParser = require('body-parser');
const mySecret = ENV['SECRET_TOKEN'];
const createComparisonSignature = (reqBody) => {
     const hmac = crypto.createHmac('sha256', mySecret);
     return hmac.update(JSON.stringify(reqBody)).digest('base64');
}
const compareSignatures = (signature, comparisonSignature) => {
     const source = Buffer.from(signature);
     const comparison = Buffer.from(comparisonSignature);
     return crypto.timingSafeEqual(source, comparison);
}
app.post('/webhookTest', bodyParser.json(), (req, res) => {
     // Extract the Docubee Generated HMAC Signature from the incoming headers
     const signature = req.headers['ontask-signature'];
     // Generate a comparison HMAC signature locally using your secret and the incoming request body
     const comparisonSignature = createComparisonSignature(req.body);
     if (!compareSignatures(signature, comparisonSignature)) {
          return res.status(401).send('Mismatched signatures');
     } else {
          return res.sendStatus(200);
     }
});
app.listen(3000, () => console.log('Example app listening'));

Reference

Related Information