Webhooks

Receive Job Events

Send a public HTTPS callback URL and optional signing secret when starting supported jobs.

curl -X POST "https://api.datablue.dev/v1/crawl" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","max_pages":10,"webhook_url":"https://hooks.example.com/datablue","webhook_secret":"YOUR_WEBHOOK_SECRET"}'

Example response

{
  "success": true,
  "job_id": "job_01HXYZ",
  "status": "queued"
}

Webhook Payload

Example

{
  "event": "job.completed",
  "job_id": "job_01HXYZ",
  "job_type": "crawl",
  "status": "completed",
  "total_pages": 10,
  "completed_pages": 10
}

Headers and Signature

Header	Use
`X-DataBlue-Event`	Event name.
`X-DataBlue-Delivery`	Unix delivery timestamp.
`X-DataBlue-Signature`	`sha256=...` HMAC when a secret is supplied.

Calculate HMAC-SHA256 over the raw request body and compare signatures with a constant-time function.

Delivery Behavior

Events include job.completed, job.failed, and crawl cancellation events.
Failed deliveries are retried up to three attempts.
Return a status below 400 to acknowledge delivery.
Use /v1/webhooks/deliveries, /v1/webhooks/test, and /v1/webhooks/stats to inspect delivery behavior.