DocuClipper logo
Docs/Help Center
Automations

Webhook Deliveries & Retries

How to read DocuClipper's webhook delivery log and how automatic retries work.

Last updated

DocuClipper logs every webhook delivery attempt so you can confirm what your endpoint returned and when. Retries are automatic — there is no manual "retry" or "replay" button — so the delivery log is a diagnostic view, and idempotency is how you recover from a missed event.

Viewing deliveries

Open the Webhooks page and open a webhook's Deliveries view. Filter the list by All, Pending, Success, or Failed. Each row shows:

  • Status: Pending, Success, or Failed.
  • Response: the HTTP status code your endpoint returned, plus the size and a SHA-256 hash of the response body. The response body itself is not stored or displayed — the hash is there to confirm two responses were identical, not to read them back.
  • Created: when the attempt was made.

To generate a delivery you can inspect, use the Test Webhook dropdown (top right) and choose Send Test: Bank Statement or Send Test: Invoice. A test delivery appears in the log with whatever status your endpoint returned.

Success and failure

A delivery is successful when your endpoint returns any 2xx status within 10 seconds. Any other status (including 3xx redirects and 5xx errors) or a timeout counts as a failure and triggers the retry policy.

Retry policy (automatic)

Failed deliveries are retried automatically — up to 3 attempts total (the initial delivery plus 2 retries) with exponential backoff starting from a ~1-second base:

  • Attempt 1: the initial delivery.
  • Attempt 2: ~1 second after the first failure.
  • Attempt 3: ~2 seconds after the second failure.

After the third attempt fails, the delivery stops retrying and is marked failed. There is no manual re-delivery or replay in the UI, so retries all happen within a few seconds of the original event.

Recovering a missed event (idempotency)

Because retries are automatic and short-lived, the reliable way to recover from a permanent failure is to make your endpoint idempotent and fix it before the next event fires:

  • Every delivery — including retries — carries the same X-DocuClipper-Event-Id header. Record IDs you've already processed and no-op on repeats.
  • Return a 2xx as soon as you've durably queued the event, then do slow work asynchronously, so a slow handler doesn't time out and fail.
  • If you've already missed an event, re-run the extraction (or fetch current job data via the API) rather than waiting for a re-delivery.

See Idempotency in the overview for handler examples.

Debugging tips

  • If your endpoint consistently returns 5xx, the delivery log confirms the status code and timing, but not your response text — reproduce locally against the test payload to see the body your handler received.
  • Verify the signature exactly as shown in Verifying signatures; a 401 in the log usually means a body-encoding mismatch.
  • For local development, tunnel with a service like ngrok and point the webhook at the tunnel URL.

Related