Webhooks

Base path: /v1/admin/webhooks

Register Webhook

POST /v1/admin/webhooks

Field	Type	Required	Description
`url`	string	yes	Delivery URL (HTTPS required, HTTP allowed for localhost)
`events`	string[]	yes	Event types: `document.processing`, `document.ready`, `document.failed`
`collections`	string[]	no	Filter by collection names (`null` = all)
`description`	string	no	Human-readable description

Response 201: Webhook object with secret field (shown once only).

curl -X POST http://localhost:6100/v1/admin/webhooks \
  -H "Authorization: Bearer $BIGRAG_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhook",
    "events": ["document.ready", "document.failed"]
  }'

List Webhooks

GET /v1/admin/webhooks?limit=50&offset=0

Get Webhook

GET /v1/admin/webhooks/{id}

Update Webhook

PUT /v1/admin/webhooks/{id}

Updatable fields: url, events, collections, description, active.

Delete Webhook

DELETE /v1/admin/webhooks/{id}

List Deliveries

GET /v1/admin/webhooks/{id}/deliveries?limit=50&offset=0

Returns delivery history for a webhook, useful for debugging.

Test Webhook

POST /v1/admin/webhooks/{id}/test

Sends a webhook.test event to verify the endpoint is reachable.

Webhook Payload

{
  "event": "document.ready",
  "timestamp": "2026-04-02T12:34:56Z",
  "collection": "docs",
  "document_id": "abc-123",
  "status": "ready",
  "chunk_count": 42,
  "error_message": null
}

Headers

Each delivery includes these headers:

X-BigRAG-Signature: sha256=<hex digest>
X-BigRAG-Event: document.ready
X-BigRAG-Delivery: <delivery-uuid>

Retry Policy

Failed deliveries retry 3 times with exponential backoff (~10s, ~30s, ~90s). After all retries, the delivery is marked as failed.

On this page