Webhooks
API endpoints for managing webhook registrations.
Base path: /v1/admin/webhooks
Session-only admin endpoints. API-key bearer tokens are rejected.
Management
Deliveries
Payload format
Webhook events use a common envelope:
{
"event": "connector.sync.completed",
"timestamp": "2026-05-22T00:00:00Z",
"collection": "docs",
"data": {
"provider": "s3",
"source_id": "source-id",
"job_id": "job-id",
"status": "complete",
"counts": {
"found": 12,
"created": 2,
"updated": 1,
"skipped": 9,
"deleted": 0,
"failed": 0
}
}
}Admin-plane events (user.create, api_key.*, webhook.*, settings changes) remain in the audit log. Per-query success webhooks are intentionally not emitted; use access logs and analytics for high-RPS query monitoring.
Headers & retry
Each delivery includes these headers:
X-BigRAG-Signature: sha256=<hex digest>
X-BigRAG-Timestamp: <unix timestamp>
X-BigRAG-Event: connector.sync.completed
X-BigRAG-Delivery: <delivery-uuid>The signature is HMAC-SHA256(secret, "{timestamp}.{raw_body}"), where timestamp is the exact X-BigRAG-Timestamp value and raw_body is the delivered JSON body bytes decoded as UTF-8.
Failed deliveries remain in the delivery outbox as pending with next_retry_at set for the next attempt. The dispatcher claims due rows, updates attempts, and marks the delivery delivered or failed once the retry budget is exhausted.