Connect webhooks with Impira

There are lots of ways to interact with your data in Impira. You can export your data via CSV, access data through API and IQL, or you can make a webhook connection.

What's a webhook?

A webhook is a user-defined HTTP callback that enables you to create a real-time conversation between a client and a server whenever a data event occurs.

In other words, by setting up a webhook with Impira, you're asking Impira (the “client”) to let you (the “server”) know about any updates or changes to your dataset.

You provide Impira with a way to reach you (via a unique webhook URL) whenever a new data event occurs. By having a webhook instantly “push” new data over to you means you won't have to check for updates yourself — you let the updates come to you.

Okay, let's get webhooked

If your receiving application allows for webhooks, find that application's unique webhook URL. ‍

1. Have your unique webhook URL handy by copying it to your clipboard.

2. Go to Impira and select your Collection.
3. Click the drop-down arrow next to the Collection's name (right below the search bar) and select Configure automations.

4. Click + on the right side, beside Destinations and select Webhook.
5. Paste in your webhook URL and choose Submit (see the Advanced options section below to further customize your webhook).

And you're done.

With just a few steps, you've linked Impira with your receiving application by creating a webhook.

Any time you add files or make changes to the data in this Collection, Impira will run an API request and send updates to the URL you provided.

Advanced options

As you set up your webhook, you can toggle Show/Hide advanced options to choose the event that triggers a webhook.

Events:

• Across all records (default option): A webhook is triggered whenever a new file has been added to the Collection and fully processed.
• Only for records with all high confidence machine learning fields: A webhook is triggered whenever a new file contains all confident predictions.
• Only for records with 1+ low confidence machine learning fields: A webhook is triggered when a new file contains at least one low confidence (i.e., “review recommended”) prediction.
• Custom IQL query: A webhook is triggered when a new file matches the definition of an IQL query entered in the field below.
  • Use this option to create webhooks for your own custom logic — e.g., triggering a webhook every time a particular extracted value contains a date after Jan. 1, 2020.

Checking on your webhook

Any time you want to see the status of any recently run webhooks, go to Configure automations (see step 3) and select View next to your webhook.

This is a good way to check when the last time a webhook was run or if there were any errors, etc.

Secure webhooks

Impira allows you to specify an optional secure token when you create a webhook. This token is used to sign your webhook, so you can validate its integrity when you receive it. If you enable secure webhooks, the HTTP request will contain a header called "impira-signature" which is a SHA-256 HMAC signature of the webhook and your key.

The following Python sample code illustrates how to validate the integrity of the signature:

import hmac
import hashlib
signature = hmac.new(secure_token.encode(), response_body.encode(), hashlib.sha256).hexdigest()

• secure_token is the token you enter into the Impira UI
• response_body is the body of the webhook itself

This signature should match the "impira-signature" value you receive in the webhook request.