Products

View Products Overview

Collect information to use in contracts and agreements.

Create contracts swiftly through templates, AI, or create and edit your own.

Route contracts seamlessly for editing, review, and approval.

Easily work with internal and external participants to edit and redline contracts in real-time

Capture secure, compliant, and legally binding signatures on any device.

Connect to the systems you use daily, or build into your application with our APIs.

How to Use Webhooks

Knowing how to use webhooks is an important step in setting up integrations between your apps. If you’re struggling with disjointed processes that require you to send documents manually from one location to another or import data, webhook integrations are a great remedy.

What is a Webhook?

A webhook is an automated message sent from one app to another when an event happens. For example, you have a webhook set up with Docubee to send a document to Google Drive once a workflow is completed, Docubee would send an automatic update to Google Drive to send the document.

Webhooks vs. APIs

Webhooks and APIs often get confused. The main difference between a webhook and an API is that webhooks work automatically to send data when a specific event triggers it. 

APIs are manual, meaning that they need to be asked to pull or make changes to data with a request from another software.

In this article, we’ll teach you how to set up Webhooks in Docubee. Let’s dive in:

The Essentials of Webhook in Docubee

This article provides information about webhooks in the following sections:

  • Webhooks Overview
  • Configuring Webhooks
  • Adding Webhooks to Your Workflows
  • Securing Your Webhooks

A More Technical Look at Webhooks

Webhooks allow you to build integrations into your workflows that subscribe to your webhook event tasks. When a webhook event task is hit during a workflow, we’ll send an HTTP POST payload to the webhook’s configured URL that contains all the workflow variables at that point in time.

Webhooks can be configured at the organization level by an organization admin or organization owner. Once the configuration is complete, you can add webhook tasks to your workflow, and the webhook will be triggered each time the workflow is run and the webhook event is hit.

What is a Webhook Payload?

A webhook is an automated message sent from an app when something happens. The message they send is also known as a payload which includes a unique URL, similar to how humans have a unique phone number.

Each payload from a workflow webhook event will contain a timestamp and the workflow variables (anything with a property name, the workflow initiator name, and the workflow initiator email) for a specific instance. 

You can configure document properties to be included in your payload under the Webhook Task Settings inside of the workflow builder.

webhook configuration

Using Headers in Webhooks

You can configure customer headers for your webhooks in Docubee to contain specific information.

HTTP POST payloads that are delivered to your webhook’s configured URL endpoint may contain the following special headers:

Header Description
content-type Indicates the media type of the resource. Will always be “application/json” for these requests.
ontask-signature The HMAC hex digest of the response body. This header will be sent if the webhook is configured with a secret. The HMAC hex digest is generated using the SHA-256 hash function and the secret as the HMAC key.

This is an example of what a payload with timestamps, the workflow initiator email, and their name would look like:

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”

     }

}

Configuring a Webhook

To use webhooks in your Docubee workflow, the first step is to configure one in the account section. Organization owners and organization admins will be able to access the Webhooks tab in your organization settings to add a webhook connection.

webhooks in organization settings

To configure a webhook connection:

Go to the Webhooks tabs in your organization settings. Webhooks require a few configuration options before you can make use of them. We’ll go through each of these settings next:

  • Webhook Name: This is 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: This is the URL of the server that will receive the webhook POST requests. It must be configured to start with https:// or  http://
  • Optional Secret Token: Setting a webhook secret allows you 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 Securing Your Webhooks for more information

Adding Webhooks To Your Workflows

To add a webhook event task to your workflow:

  1. Open the add task selector, go to the “Send and Save” section, and click “Webhook”. Everyone who has permission to build workflows will be able to add webhook tasks.
    webhook selection in send and save task
  2. Once you add a webhook task, you will see a right-side panel with configuration options.

    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. 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.Select the webhook connection you would like to send the request to from the dropdown menu. Use the toggle to choose whether or not to suspend a workflow on a webhook failure. 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 would like the workflow to suspend instead and stop proceeding, switch the toggle on.
  3. Once you have those options configured, you may add any other steps to your workflow as needed before you publish and run it. You can also toggle on the “Include document identifiers” option here to include document properties.
    task configuration and label for webhook set up

How to Secure a Webhook

To help ensure the security of your system, we recommend that you restrict requests to only those originating from Docubee. Setting a secret token for your webhook will allow you to verify the authenticity of the incoming information.

Setting Your Secret Token

You will need to set up your secret token when you configure your webhook in Docubee, as well as on your server. When creating your secret token, we recommend using a random string with high entropy. 

After entering it in the webhook configuration step in Docubee, you should create an environment variable on your server that stores this token; this can be as simple as running:

export SECRET_TOKEN=your_token

Call out: Please note: We never recommend hard-coding your secret token into your app.

Validating Payloads from Docubee

When you have a secret token configured, Docubee will use it to create a hash signature with each payload. 

This hash signature is passed along with each request in the headers as ontask-signature. The code snippet below demonstrates a basic server listening for webhook requests with a secret configured. 

The goal is to compute a hash using your SECRET_TOKEN, and ensure that the hash from Docubee matches. Docubee uses a SHA-256 HMAC base64 digest to compute the hash, so you could do something like this on your server:

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

Portions of this article were excerpted from: https://developer.github.com/webhooks/.

Need more help to configure your webhooks? Contact us for assistance.