Skip to main content
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 typeSent whendata payload
knowledge.processing.completedKnowledge processing transitions to ready.Knowledge processing summary with knowledge_id, teamspace_id, scope, status, and row_counts.
batch_prediction.completedA batch prediction reaches completed.The batch_prediction object.
batch_prediction.failedA batch prediction reaches failed.The batch_prediction object.
batch_prediction.expiredA batch prediction reaches expired.The batch_prediction object.
batch_prediction.cancelledA 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.