Configuration

Setting up a webhook

To set up a webhook, you can create one in the “Developers” tab on the sidebar, under the “webhook endpoints” section.

Global webhooks

To receive events for webhooks you need to subscribe to events. When creating a webhook endpoint, you can subscribe to the GLOBAL event types. These events are not associated with a specific workflow or processor and are global to your workspace.

See the Events section for more details on the different event types you can subscribe to.

Webhook delivery format

We support two delivery formats for webhooks:

• JSON: This is the default and most common format. It is a simple JSON object with the event data in the body.
• Signed Download URL: This is a signed URL that allows you to download the event data as a file. This is useful for scenarios where the webhook event payload is too large to fit in the body of the request, or you have payload size constraints on your webhook endpoint.

We also provide the option to send all payloads as a signed download URL over a certain size threshold, which can be configured in bytes when creating/updating a webhook endpoint.

The signed download URL has a one hour expiration time. When manually re-trying a webhook request, a new URL will be generated each time, and when viewing the webhook history for events sent as a URL, a new URL is generated for viewing.

To configure the delivery format, you can select the desired format in the “Advanced options” dropdown when creating/updating a webhook endpoint.

Workflow specific subscriptions

After you have created one or more webhook endpoints from the “Developer” tab, you can subscribe to events for specific workflows by navigating to the desired workflow(s) and opening the “Webhook Subscriptions” menu.

Then you can create new subscriptions for the desired endpoints and event types.

Once subscribed, you will start to receive events to the specified webhook endpoint based on the selected event types each time you run a file(s) through that workflow.

See the Events section for more details on the different event types you can subscribe to and the shape of the payload for each event type.

Processor run specific subscriptions

You can also subscribe to events for specific processor runs. This is necessary if you are running processors directly and not via a workflow.

To start, navigate to the “Overview” tab of the given processor in Studio, click “Webhook Subscriptions”, and then click the “Add webhook subscription” button.

Next, you can select the desired event types you would like to subscribe to and assign the webhook endpoint you would like to receive events at.

Verifying webhook requests from Extend

Extend will sign each webhook request using a secret unique to the webhook. You can use this signature along with the timestamp to verify that the request is coming from Extend as well as protect against replay attacks.

Steps to verify a webhook request from Extend

At a high level, the steps to verify a webhook request from Extend are

1. Retrieve the timestamp of the request from x-extend-request-timestamp, the body of the request, and the signing secret associated with the webhook.
2. Concatenate the timestamp and request body using the following format: v0:${timestamp}:${requestBody}
3. Compute a HMAC 256 digest on the resulting string using the signing secret as the key. The secret can be found in the webhooks table under the “Developer” tab

4. Compare this digest with the signature provided in x-extend-request-signature. If they are equal, then the request is verified to be from Extend.

Here is pseudocode in Javascript to perform the verification:

1
import crypto from "crypto";
2
3
const timestamp = request.headers['x-extend-request-timestamp'];
4
const receivedSignature = request.headers['x-extend-request-signature'];
5
const signingSecret = "wss_C...l";
6
7
// validate timestamp to prevent replay attacks
8
const currentTime = Math.floor(Date.now() / 1000);
9
if (currentTime - parseInt(timestamp) > 300) { // 5 minutes
10
  throw new Error('Request timestamp too old');
11
}
12
13
const requestBodyString = JSON.stringify(request.body);
14
15
// retrieve from the webhook details on the "Developers" tab
16
17
const message = `v0:${timestamp}:${requestBodyString}`;
18
const expectedSignature = crypto
19
  .createHmac("sha256", signingSecret)
20
  .update(message)
21
  .digest("hex");
22
23
if (expectedSignature !== receivedSignature) {
24
  throw new Error('Invalid webhook signature');
25
}
26
27
// proceed with webhook processing