{
  "id": 20637477,
  "title": "Idempotent webhooks in Node.js: handle every event once, even when it's delivered twice",
  "url": "https://urgent.news/2026/11/18/idempotent-webhooks-in-node-js-handle-every-event-once-even-when-its",
  "topic": "tech",
  "section": "Tech",
  "published": "2026-11-18T18:37:58.000Z",
  "source": {
    "name": "Dev.to",
    "slug": "dev-to",
    "url": "https://dev.to/quantumbreakz/idempotent-webhooks-in-nodejs-handle-every-event-once-even-when-its-delivered-twice-2a4n"
  },
  "original_language": "en",
  "account": "Webhook providers deliver events at least once. If your endpoint is slow, returns an error, or the response is lost, the same event is sent again. To handle this, you need an idempotent handler that claims the event ID in the database with a unique constraint. If the work fails, you mark it as done and release the claim so the retry can run it. The claim must be an atomic operation to prevent duplicate processing when multiple deliveries arrive together. Responding with a 200 status before doing the work allows a crash to lose the event entirely and for the provider to retry. The event ID should be used as a primary key in the database. Use the same SQL for PostgreSQL as well. The claim checks if the event is still processing and has been untouched for five minutes, indicating the original worker is dead and the new delivery takes it over. If the side effect fails, the claim is released, allowing a retry. This method ensures the side effect runs at most once at a time and once after it succeeds. However, if the email is sent and the process crashes, the email may be sent again due to the gap between the claim and the finish operation. This cannot be fully resolved within the database alone since the email provider is separate. To make the side effect itself idempotent, pass an idempotency key to the downstream API when supported. Use that key in the same transaction when making changes to the database. This way, repeats are harmless. Verify the signature first to prevent forged requests from filling your table. Don't rely on the event coming from localhost as proof of authenticity. Respond quickly to prevent queue buildup if the work is slow. Use the provider's event ID, not a body hash. Retries might differ in fields like delivery timestamp. Delete old rows after the provider's retry window has passed to keep the database clean.",
  "summary": "Webhook providers deliver at least once : if your endpoint is slow, returns an error, or the response is lost on the way back, they send the same event again. A handler that sends an email or charges a card on every delivery will eventually do it twice. The fix is an idempotent handler : claim the event ID in the database with a unique constraint before doing the work, mark it done afterwards,…",
  "key_points": [
    "Webhook providers deliver events at least once, requiring idempotent handling.",
    "Claim event ID in database with unique constraint to prevent duplicate processing.",
    "Respond quickly and use provider's event ID to maintain idempotency and clean database."
  ],
  "editors_take": null,
  "illustration": null,
  "coverage": {
    "outlets": 1,
    "also_reported_by": []
  },
  "ai_generated": true,
  "disclaimer": "Summaries, key points and the editor’s take are written by software from other outlets’ reporting and may contain errors — always check the linked original."
}