Reliable Webhook Processor

Any integration that receives webhooks eventually hits duplicate delivery, partial processing and provider retries. The naive handler quietly corrupts state.

Webhooks arrive more than once, out of order, and sometimes while your worker is dying. This project handles those cases explicitly rather than hoping they do not happen.

Processing an event twice must not produce two effects, and a worker crashing mid-job must not lose the event or leave it locked forever.

• Providers guarantee at-least-once delivery, never exactly-once
• Acknowledgement must be fast; the work must not happen in the request
• Failures must be visible, not swallowed

• 01

  Receive endpoint persists the raw event with a provider-supplied idempotency key, then acknowledges immediately

• 02

  PostgreSQL holds the event ledger and its processing state — no in-memory queue as the source of truth

• 03

  Background workers claim events atomically, so a crashed worker's claim expires and the event is reprocessed

• 04

  Retries use exponential backoff with an explicit attempt ceiling and a dead-letter state

• Duplicate deliveries produce a single effect
• Worker failure mid-processing recovers without intervention or data loss
• Failed events are inspectable and replayable rather than silently dropped

Most reliability comes from the database, not the application code. Once state lives in one durable place with the right constraints, recovery becomes almost boring.