Skip to content

LearnOperate

Webhooks

HTTP callbacks a service sends to your URL when something happens, such as a run finishing, so you react to events instead of polling for them.

In DocSlurpGlossary entry

On this page

A webhook is an HTTP request a service sends to a URL you register when an event happens. Instead of polling “is my run finished yet?” every few seconds, you get a POST when it is:

{ "event": "run.completed", "runId": "run_123", "projectId": "ws_123",
  "status": "completed", "processedDocuments": 14, "pagesProcessed": 942 }

Verify every delivery

Your endpoint is a public URL, so anyone can POST to it. Webhook senders therefore sign each delivery with a secret shared only with you. DocSlurp sends:

X-DocSlurp-Signature: t=1767225600,id=<delivery id>,v1=<hex HMAC-SHA256>

The HMAC covers timestamp.deliveryId.body. To verify, recompute it over the raw request body exactly as received (parsing and re-serializing JSON changes the bytes), compare in constant time, and reject timestamps more than a few minutes old so a captured request can’t be replayed later.

Expect duplicates and gaps

Delivery over the internet is unreliable in both directions. A sender may deliver an event twice, for example after a crash mid-delivery, and a receiver may be down when an event arrives. Make your handler idempotent: key on the event and its subject (for example run.completed plus runId) and ignore repeats. Return 2xx quickly and do slow work afterwards; a slow response looks like a failure.

In DocSlurp, events are written to an outbox and sent by the API, which checks the target URL against private-network addresses first. A delivery that gets a non-2xx response is recorded in the delivery log but is not retried automatically, so for anything critical, keep polling the run or job status as a fallback, and replay missed deliveries from the log. Events include run.completed, run.failed, document.extracted and document.replaced.

In DocSlurp

In DocSlurp

Events such as run.completed and document.replaced are signed with HMAC-SHA256 over timestamp.deliveryId.body and sent from an outbox with SSRF checks (core/server/src/services/webhooks.ts). A non-2xx response is recorded per delivery but not retried automatically; replay it from the delivery log.

Sources

Jump to