Skip to content
Prividium

Webhook Delivery Handling

This page focuses on receiver behavior after you register webhook endpoints.

Delivery Model

  • Each delivery includes Standard Webhooks headers: webhook-id, webhook-timestamp, and webhook-signature.
  • webhook-id is unique per event and stable across retries.
  • Use webhook-id as your idempotency key.

Receiver Processing Checklist

  1. Read the raw request body bytes.
  2. Verify signature and timestamp before processing.
  3. Deduplicate by webhook-id.
  4. Process business logic only once per idempotency key.
  5. Return a success response after processing.

Idempotency and Retry Guidance

Because webhook-id is stable across retries, retries should not produce duplicate side effects if your receiver is idempotent.

Recommended pattern:

  • Persist webhook-id in durable storage before applying side effects.
  • If the same webhook-id is seen again, treat it as a duplicate delivery.
  • Keep handlers deterministic and safe to re-run.

Failure Handling

If signature verification fails:

  • Return a 4xx response (typically 401 or 400).
  • Do not process the payload.
  • Do not retry internally.

Common Pitfalls

  • Verifying parsed JSON instead of the raw body bytes.
  • Performing non-idempotent writes without checking webhook-id.
  • Dropping duplicate deliveries without recording prior processing state.