> ## 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](/api-reference/batch-predictions/retrieve-batch-prediction-results) 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.