Webhooks overview

Subscribe to Datagrid events and receive signed HTTPS callbacks.

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.