Writing Idempotent Webhooks: Patterns That Survive Retries

Описание и применение

Webhook‑события часто повторяются, что приводит к двойным операциям. Используя таблицу dedupe, проверку состояния и быстрый ответ, можно сделать обработку идемпотентной и избежать двойных платежей.

Задача

Webhook providers often retry events, causing duplicate processing and potential double charges or state corruption.

Результат

Duplicate webhook deliveries are now harmless; orders are only charged once, state transitions are atomic, and retries are suppressed by fast 2xx responses.

Рабочий процесс

• Validate signature using raw body HMAC
• Attempt to insert event ID into processed_events table with ON CONFLICT DO NOTHING
• If insert succeeds, enqueue raw payload and return 200 quickly
• If insert fails, read current business state (e.g., order status)
• If state already reflects desired outcome, return 200 without side effects
• Otherwise perform conditional update to transition state only if still pending
• Handle side effects (charge, email, etc.) after state transition
• If worker crashes, queue redelivers and readback guards against repeat work

Доказательства

Every webhook arrives twice eventually, so design for it from day one

Источник

A unique dedupe key plus a processed-events table kills double-acts

Источник

Read current state before acting so a retry is a no-op

Источник

Return 2xx fast, do the slow work after you confirm it hasn't run

Источник