Getting Started with Inscribe Webhooks

Webhooks allow you to receive notifications for Inscribe’s fraud and verification results in real-time to a URL that you specify. This is the preferred method for high-volume processing of notifications and allows you to programatically hook into the lifecycle of your documents and customers in Inscribe to act on any of the results.

Creating a Webhook

Most users configure their webhooks from the notification settings page, which provides an interface for registering and editing your webhooks. Only admins within your Inscribe organization will have permission to view and manage webhooks.

Creating a new webhookCreating a new webhook

Creating a new webhook

You can also create and configure webhooks via the Inscribe API.

Note that new webhooks will need to be approved by Inscribe before they are operational. Once your webhook is approved you will begin to receive notification payloads from Inscribe at the specified URL. It is important that you ensure that the payload you are receiving on your webhook comes from Inscribe. Details on securing your webhooks are provided below in the "Securing your Webhooks" section.

Editing your Webhook

Using the notification settings page you can edit the URL and type of your webhook.

Webhook Types

We currently support four different types of webhooks.

Document State Changed

This webhook type is the default for newly created webhooks. It will send a request to your chosen URL whenever the state of a document changes. The body of the request will contain a document result object in the same format as the "Get Document Results" API.

Collect Session Completed

This webhook type will send on successful completion of a collect session by your customer. The body of the request will contain a collect session object in the same format as the "Get Collect Session" API.

Customer Approval Status Changed

This webhook type will send when a customer’s approval status is changed to either "Approved" or "Rejected". The body of the request will contain the relevant customer object in the same format as the "Get Customer" API.

Document Processed (Deprecated)

This webhook type will send on successful completion of document processing. The body of the request will contain a document result object in the same format as the "Get Document Results" API.

🚧

This webhook type has been deprecated. If you are currently using this webhook type and wish to switch to the new "Document State Changed" webhook type, please create a new webhook and use that. It will default to the "Document State Changed" webhook type.

Securing your Webhooks

The nature of webhook delivery requires that the URL that will receive the requests is publicly accessible over the internet. When you have set up your webhooks, for security purposes you will want to verify that incoming requests are coming from Inscribe and not any other potentially malicious 3rd-party that has the URL. In order to accomplish this, we assign a unique secret to each webhook you create. These are viewable for each webhook on the notification settings page.

An example webhook with a secret tokenAn example webhook with a secret token

An example webhook with a secret token

Inscribe uses this secret token to create a hash signature with each payload, which we send as a header, called X-INSCRIBE-SIGNATURE.

In order to validate that the request came from Inscribe, you can compute your own signature with the secret token and the webhook request body. Inscribe uses a HMAC hexdigest to compute the signature with SHA256. Below is an example of a function in Python that can verify an incoming request body string and signature using your secret.

import hashlib
import hmac


def signature_is_valid(request_body_string, secret, request_signature):
    computed_signature = hmac.new(
        secret.encode("utf-8"),
        request_body_string,
        hashlib.sha256,
    ).hexdigest()

    return hmac.compare_digest(computed_signature, request_signature)

Testing your Webhooks

In order to get an idea of how Inscribe webhooks work and what the shape of the incoming data looks like it is often a good idea to set up a test server and inspect the requests that come into it. This can also be useful to verify your implementation of the webhook signature check works as expected or to test integration of webhooks into your application.
Setting up a local server to receive webhooks from Inscribe can be accomplished with tools like ngrok which allow you to set up a public URL that tunnels to a server running on your local computer.

The first step is to run your test server. For this example we’re going to use the following Python code using the Flask web framework. This example server uses the function we defined before to verify the signature of incoming webhook payloads.

import hashlib
import hmac
from flask import Flask, request


SECRET = "YOUR_WEBHOOK_SECRET_HERE"

app = Flask(__name__)


def signature_is_valid(request_body_string, secret, request_signature):
    computed_signature = hmac.new(
        secret.encode("utf-8"),
        request_body_string,
        hashlib.sha256,
    ).hexdigest()

    return hmac.compare_digest(computed_signature, request_signature)


@app.route("/", methods=["POST"])
def webhook_handler():
    request_signature = request.headers.get("X-INSCRIBE-SIGNATURE")
    request_body_string = request.get_data()

    # Ensure the request came from Inscribe
    if signature_is_valid(request_body_string, SECRET, request_signature):
        print("VALID SIGNATURE")

        # Do interesting things with the data in the webhook.
        print(request_body_string)

        return '', 204

    else:
        print("INVALID SIGNATURE")
        # The signature was invalid. We should not trust that the incoming
        # webhook data was sent by Inscribe to the webhook. It may be data
        # sent by a malicious 3rd party actor. Just send back an empty response.

        return '', 204

We can start the local server for this example on port 5000 (the default for Flask) by saving this code as app.py and running the following:

$ flask run

We can then tell ngrok to create a public URL for our local server that we have running on port 5000 with the following command

$ ngrok http 5000
An example ngrok tunnel pointing at port 5000 on localhostAn example ngrok tunnel pointing at port 5000 on localhost

An example ngrok tunnel pointing at port 5000 on localhost

The public URL ngrok gives us can be entered on the webhook settings page and you should start to receive webhooks to our server when the appropriate lifecycle event happens in Inscribe. Using the "Customer Approval Status Changed" webhook type for example we can see notifications come through to the local test server through the ngrok tunnel when customers are approved and rejected.

Example console output of our local server when receiving a webhookExample console output of our local server when receiving a webhook

Example console output of our local server when receiving a webhook

As you can see we were able to receive a webhook payload to our local server using ngrok, verify the signature of the request using the secret token and log some information from the payload.

Inscribe's Egress IP Addresses

You may wish to allow-list Inscribe's egress IP addresses for added security:

  • 52.88.6.127
  • 44.238.187.155

Did this page help you?