> ## Documentation Index
> Fetch the complete documentation index at: https://developers.datagrid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://developers.datagrid.com/api-reference/batch-predictions/retrieve-batch-prediction-results.md) when you need the full NDJSON result stream.

## Create a subscription

```bash theme={null}
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:

```json theme={null}
{
  "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:

```text theme={null}
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.