Configuration

Webhooks push events to your server as work completes, so you don’t have to poll for results. You can configure them in the dashboard or with the API — both use the same two building blocks described below.

How webhooks work

Two concepts work together:

• Endpoint — a destination URL that receives events, along with a signing secret used to verify them. Each endpoint is pinned to a single API version.
• Subscription — what an endpoint listens for. There are two kinds, and an endpoint can use both at once:
  • Global events are set directly on the endpoint (its enabledEvents). They fire for every resource of that type in the workspace, plus workspace-level lifecycle events like extractor.created and workflow.deployed.
  • Resource-scoped subscriptions bind an endpoint to a single resource — one extractor, classifier, splitter, or workflow — so you only receive that resource’s events.

Run events are only delivered for runs created through the API — runs started from the dashboard do not trigger webhooks.

Set up a webhook in the dashboard

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

Subscribe to global 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.

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.

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.

Configure webhooks with the API

Everything you can do in the dashboard you can also do programmatically. This is the path to reach for when you provision webhooks per customer or environment, manage them in infrastructure-as-code, or let an agent wire up its own event delivery.

Create an endpoint

Creating an endpoint registers a URL and sets its global enabledEvents. The response includes a signingSecret — it is returned only once, so store it securely. You’ll need it to verify deliveries.

$
curl -X POST https://api.extend.ai/webhook_endpoints \
>
  -H "Authorization: Bearer YOUR_API_KEY" \
>
  -H "x-extend-api-version: 2026-02-09" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "url": "https://example.com/webhooks",
>
    "name": "Production webhook",
>
    "enabledEvents": ["extract_run.processed", "extract_run.failed"],
>
    "apiVersion": "2026-02-09"
>
  }'

Subscribe to a specific resource

To receive events for a single resource, create a subscription against an existing endpoint. Set the resourceType (extractor, classifier, splitter, or workflow), the resourceId, and the enabledEvents that are valid for that resource type. If a subscription already exists for the same endpoint and resource, it is updated rather than duplicated.

$
curl -X POST https://api.extend.ai/webhook_subscriptions \
>
  -H "Authorization: Bearer YOUR_API_KEY" \
>
  -H "x-extend-api-version: 2026-02-09" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "webhookEndpointId": "wh_Xj8mK2pL9nR4vT7qY5wZ",
>
    "resourceType": "workflow",
>
    "resourceId": "workflow_id_here",
>
    "enabledEvents": ["workflow_run.completed", "workflow_run.failed"]
>
  }'

The valid enabledEvents for a subscription depend on its resourceType:

Manage endpoints and subscriptions

Both resources support the full set of list, retrieve, update, and delete operations. A few things to know:

• Updates are partial — only the fields you send are changed. An endpoint’s apiVersion cannot be changed after creation.
• Deleting an endpoint also deletes all of its subscriptions, and is permanent.
• Filtering — list subscriptions by webhookEndpointId to see everything an endpoint listens for, or by resourceId to see every endpoint a resource notifies.

See the API reference for the full schemas and every operation: Create Webhook Endpoint and Create Webhook Subscription.

Verifying webhook requests

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
from extend_ai import Extend
2
from extend_ai.wrapper.errors import WebhookSignatureVerificationError
3
4
client = Extend(token="YOUR_API_KEY")
5
6
@app.post("/webhook")
7
def handle_webhook(request):
8
    try:
9
        # verify_and_parse validates the signature and parses the event in one step
10
        event = client.webhooks.verify_and_parse(
11
            body=request.body.decode(),      # Raw request body as string
12
            headers=dict(request.headers),   # Request headers as dict
13
            signing_secret="wss_your_signing_secret"  # Your webhook signing secret
14
        )
15
16
        # Handle the event based on type
17
        if event["eventType"] == "workflow_run.completed":
18
            print("Workflow completed:", event["payload"])
19
        elif event["eventType"] == "extract_run.processed":
20
            print("Extract run processed:", event["payload"])
21
        # ... handle other event types
22
23
        return {"status": "ok"}
24
    except WebhookSignatureVerificationError:
25
        return {"error": "Invalid signature"}, 401

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
event = client.webhooks.verify_and_parse(body, headers, secret, allow_signed_url=True)
2
3
if client.webhooks.is_signed_url_event(event):
4
    # Fetch the full payload from the signed URL
5
    full_event = await client.webhooks.fetch_signed_payload(event)
6
    print("Full payload:", full_event["payload"])
7
else:
8
    # Normal inline payload
9
    print("Payload:", event["payload"])

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 hmac
2
import hashlib
3
import time
4
5
timestamp = request.headers.get('x-extend-request-timestamp')
6
received_signature = request.headers.get('x-extend-request-signature')
7
signing_secret = "wss_your_signing_secret"
8
9
# Validate timestamp to prevent replay attacks
10
current_time = int(time.time())
11
if current_time - int(timestamp) > 300:  # 5 minutes
12
    raise ValueError('Request timestamp too old')
13
14
request_body_string = request.body.decode()
15
16
message = f"v0:{timestamp}:{request_body_string}"
17
expected_signature = hmac.new(
18
    signing_secret.encode('utf-8'),
19
    message.encode('utf-8'),
20
    hashlib.sha256
21
).hexdigest()
22
23
if not hmac.compare_digest(expected_signature, received_signature):
24
    raise ValueError('Invalid webhook signature')
25
26
# Proceed with webhook processing