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.

Using the SDK (Recommended)

The easiest way to verify webhook requests is using the SDK’s built-in helper methods. These handle signature verification, timestamp validation, and event parsing automatically.

1
import { ExtendClient } from "extend-ai";
2
3
const client = new ExtendClient({ token: "YOUR_API_KEY" });
4
5
app.post("/webhook", (req, res) => {
6
  try {
7
    // verifyAndParse validates the signature and parses the event in one step
8
    const event = client.webhooks.verifyAndParse(
9
      req.body.toString(),       // Raw request body as string
10
      req.headers,               // Request headers
11
      "wss_your_signing_secret"  // Your webhook signing secret
12
    );
13
14
    // Handle the event based on type
15
    switch (event.eventType) {
16
      case "workflow_run.completed":
17
        console.log("Workflow completed:", event.payload);
18
        break;
19
      case "extract_run.processed":
20
        console.log("Extract run processed:", event.payload);
21
        break;
22
      // ... handle other event types
23
    }
24
25
    res.status(200).send("OK");
26
  } catch (err) {
27
    if (err.name === "WebhookSignatureVerificationError") {
28
      res.status(401).send("Invalid signature");
29
    } else {
30
      res.status(500).send("Internal error");
31
    }
32
  }
33
});

The signing secret can be found in the webhooks table under the “Developer” tab:

Handling Signed URL Payloads

For large payloads, webhooks may be delivered via a signed URL instead of inline. To handle these:

1
const event = client.webhooks.verifyAndParse(body, headers, secret, { allowSignedUrl: true });
2
3
if (client.webhooks.isSignedUrlEvent(event)) {
4
  // Fetch the full payload from the signed URL
5
  const fullEvent = await client.webhooks.fetchSignedPayload(event);
6
  console.log("Full payload:", fullEvent.payload);
7
} else {
8
  // Normal inline payload
9
  console.log("Payload:", event.payload);
10
}

Manual Verification

If you’re not using the SDK, you can verify webhook signatures manually:

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.
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.

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_your_signing_secret";
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
const message = `v0:${timestamp}:${requestBodyString}`;
16
const expectedSignature = crypto
17
  .createHmac("sha256", signingSecret)
18
  .update(message)
19
  .digest("hex");
20
21
if (expectedSignature !== receivedSignature) {
22
  throw new Error('Invalid webhook signature');
23
}
24
25
// Proceed with webhook processing