Webhooks overview

Webhooks let your application react when asynchronous Datagrid work finishes. Create a webhook with an HTTPS url and one or more event types, then verify each delivery with the signing secret returned at creation time.

Supported events

Event type	Sent when	`data` payload
`knowledge.processing.completed`	Knowledge processing transitions to `ready`.	Knowledge processing summary with `knowledge_id`, `teamspace_id`, `scope`, `status`, and `row_counts`.
`batch_prediction.completed`	A batch prediction reaches `completed`.	The `batch_prediction` object.
`batch_prediction.failed`	A batch prediction reaches `failed`.	The `batch_prediction` object.
`batch_prediction.expired`	A batch prediction reaches `expired`.	The `batch_prediction` object.
`batch_prediction.cancelled`	A batch prediction reaches `cancelled`.	The `batch_prediction` object.

For batch prediction events, treat the webhook as a terminal-state notification. Call Retrieve batch prediction results when you need the full NDJSON result stream.

Create a subscription

curl --request POST "$DATAGRID_API_URL/v1/webhooks" \
  --header "Authorization: Bearer $DATAGRID_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "url": "https://example.com/webhooks/datagrid",
    "events": [
      "batch_prediction.completed",
      "batch_prediction.failed"
    ]
  }'

The create response includes secret once. Store it securely; later retrieve and list responses do not include the secret.

Delivery format

Datagrid sends a JSON envelope to your endpoint:

{
  "id": "evt_7f3d8a2c",
  "event_type": "batch_prediction.completed",
  "timestamp": 1775847600,
  "data": {
    "object": "batch_prediction",
    "id": "bpred_abc123",
    "status": "completed",
    "results_url": "/v1/batch-predictions/bpred_abc123/results"
  }
}

Return a 2xx response after persisting the event. Use id as an idempotency key because Datagrid may retry failed deliveries.

Signature verification

Each delivery includes a Datagrid-Signature header:

t=1775847600,v1=<hex_hmac_sha256>

Compute the expected v1 with HMAC-SHA256 over ${timestamp}.${raw_body} using the webhook secret, then compare it with the header value using a constant-time comparison.

Delete secret Create webhook

⌘I

Introduction

Converse

Voice

Identity

Agents

Knowledge

Search

Conversations

Messages

Connections

Connection Providers

Connectors

Files

Tools

Secrets

Webhooks

Memory

Pages

MCP Servers - Beta

Batch Predictions

Organization

Supported events

Create a subscription

Delivery format

Signature verification

​Supported events

​Create a subscription

​Delivery format

​Signature verification

Supported events

Create a subscription

Delivery format

Signature verification