01
what a webhook receiver has to survive
If your product takes webhooks from Stripe, GitHub, Shopify or a CRM, the provider is sending you events at least once, in no particular order, and with a timeout on your response. Stripe's docs say it retries failed deliveries for up to three days with exponential backoff in live mode (three times over a few hours in a sandbox), that endpoints may occasionally receive the same event more than once, and that it doesn't guarantee events arrive in the order they were generated. GitHub asks for a 2xx within 10 seconds and, per its docs, doesn't automatically redeliver failed deliveries at all, so an outage on your side means lost events unless you redeliver them yourself. Both providers tell you to return quickly and do the real work asynchronously.
That gives the receiver four jobs: check that the request really came from the provider, store it durably, acknowledge fast, and process it later in a way that tolerates duplicates, retries and reordering. Teams often reach for RabbitMQ or SQS at this point. If you already run Postgres and the volume is modest, a table does all four jobs, it's queryable when something goes wrong, and replaying a failed event is an UPDATE.
A note on naming, because the pattern gets mislabelled a lot: this is an inbox. A transactional outbox solves the opposite problem, publishing events reliably together with your own database writes. An inbox records messages you received so you can deduplicate and process them reliably. The examples below are Go with pgx v5 and were run against Postgres 18, but nothing in them is Go-specific.
02
verify the signature on the raw body
An unauthenticated webhook endpoint is an open API for marking invoices paid. Every serious provider signs its requests with an HMAC over the body, and the check has to happen on the raw bytes, before any JSON parsing, because re-serialized JSON won't produce the same signature. GitHub sends X-Hub-Signature-256: sha256=<hex>, an HMAC-SHA256 of the payload with your webhook secret (the older X-Hub-Signature uses SHA-1 and exists only for legacy reasons). Compare in constant time:
Stripe's scheme adds a timestamp to stop replays. The Stripe-Signature header carries t=<unix time> and one or more v1= signatures, the signed string is the timestamp, a dot and the raw body, and the official libraries reject anything older than five minutes by default. During a secret rotation the header can carry one v1 signature per active secret. In Go, webhook.ConstructEvent from stripe-go does all of that, so use it rather than reimplementing it. Whatever the provider, reject a bad signature with a 4xx before writing anything, and cap the body size so nobody can stream gigabytes at the endpoint.
03
the inbox table and deduplication on insert
The table is the queue, the dedup index and the dead-letter store at once:
Deduplication is the unique constraint plus INSERT ... ON CONFLICT DO NOTHING. Checking with a SELECT first is a race, because two deliveries of the same event can both pass the check before either inserts. The conflict target has to match a real constraint exactly: with unique (source, event_id) in the schema, writing on conflict (event_id) fails with there is no unique or exclusion constraint matching the ON CONFLICT specification. The handler stores the event and acknowledges, and does nothing else:
A duplicate gets the same 202 as a first delivery, which is what you want, since the provider only needs to know you have it. Pick the dedup key per provider. GitHub's X-GitHub-Delivery stays the same when you request a redelivery, so it identifies the delivery. For Stripe, use the event's id from the verified body. Stripe's docs also mention that in some cases it generates two separate event objects for the same change, so if that matters for a handler, dedup on the data.object id together with the event type as well. Scoping the key by source keeps two providers with colliding id formats from deduplicating each other.
The partial index only covers pending rows, so it stays small no matter how much processed history the table keeps, and the worker's query never touches finished events.
04
claiming work without processing it twice
The worker is where most homemade inboxes break. A common version selects a batch with FOR UPDATE SKIP LOCKED, commits, and then processes the rows. Committing releases the row locks immediately, so a second worker can select the same rows a moment later and both process them. Row locks only protect you while the transaction that took them is open.
The simplest correct design processes one event per transaction and keeps the row locked until the result is committed:
Run as many goroutines calling processOne in a loop as you like. SKIP LOCKED makes each one take a different row instead of queueing behind the others, and if a worker crashes mid-event, its transaction rolls back and the row is simply pending again. The handler receives the transaction, which is the important part: when its side effects are database writes, they commit in the same transaction that marks the event done, so a crash can never leave an event processed but not marked, or marked but not processed. tx.Begin on a pgx transaction creates a savepoint, which lets a failing handler's partial writes roll back while the worker keeps its lock and records the failure. A test with eight concurrent workers, a thousand deliveries with a fifth of them sent twice, and a handler that failed randomly one time in five ended with exactly one side-effect row per event and the always-failing event marked dead after eight attempts.
05
slow handlers, external calls and ordering
Holding a transaction open is fine for handlers that take milliseconds. It's a bad idea for one that calls a slow external API, because the connection sits idle in transaction, holds a pool slot and stops vacuum from cleaning up. For those, claim the row with a lease instead and commit straight away. Reusing next_attempt_at as the lease expiry avoids an extra column:
The worker does its work and then sets status = 'done'. If it dies, the row becomes due again when the lease runs out. The price is that a handler which outlives its lease can run twice, so the side effect itself has to be idempotent. Payment and email APIs often accept an idempotency key (Stripe's API takes an Idempotency-Key header); derive it from the inbox row, such as source plus event_id, so a second run repeats the same request instead of creating a second charge or email. Check how long the API remembers keys: Stripe's docs say v1 keys can be pruned once they're 24 hours old, so they protect against a quick retry, not against replaying a week-old dead event. For writes to your own database, a unique constraint on something like (source, event_id) in the target table does the same job.
Ordering is the other trap. Since providers don't promise order, a subscription.updated can arrive after the subscription.deleted that followed it. Either compare a version or timestamp on the object before applying an update, or treat the webhook as a notification and fetch the current state of the object from the provider's API before acting. The second approach costs an API call and removes a whole class of bugs.
06
retries, dead letters and replay
The failure branch in processOne is the whole retry policy: exponential backoff from baseDelaySecs, and after maxAttempts the row becomes dead with the last error kept next to the payload. There's no separate dead-letter table to keep in sync, so you have one source of truth, and the raw payload is right there when you're debugging an event that died last week.
Replaying is SQL. To retry everything GitHub sent this week that died:
Monitoring is SQL too. This query, run on a schedule or as a dashboard panel, shows backlog and failures per provider:
Alert on the age of the oldest pending row and on any new dead rows, not on CPU. Finished rows don't need to live forever, so delete done rows older than your retention window in batches from a scheduled job, which also keeps the table and its indexes compact.
07
when you need a real broker
A Postgres inbox handles the load most products see from payment, Git and CRM webhooks, since a few thousand events a minute is under a hundred inserts a second plus the same number of small updates. It stops being the right tool when you need several independent consumers for the same event, fan-out to other services, strict per-key ordering at high throughput, or volumes where the update churn on one hot table starts to show up in autovacuum and replication lag. Those are the problems Kafka, RabbitMQ and SQS were built for, and paying their operational cost makes sense once you have them.
Below that point, the table is easier to run and easier to debug, and moving to a broker later is a contained change, because the boundary is already clean: one handler writes verified events, and workers consume them through a single function.
