[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"blog-en-stripe-webhook-idempotency-duplicates":3},{"id":4,"title":5,"author":6,"body":7,"cover":376,"description":377,"draft":378,"extension":379,"locale":380,"meta":381,"navigation":382,"path":383,"publishedAt":384,"seo":385,"seoTitle":386,"slug":387,"stem":388,"tags":389,"__hash__":391},"blog\u002Fen\u002Fblog\u002Fstripe-webhook-idempotency-duplicates.md","Stripe webhooks: idempotency, duplicates, and concurrency","Manuel Tardivo",{"type":8,"value":9,"toc":365},"minimark",[10,36,55,60,63,102,106,159,168,172,180,189,193,219,223,226,241,245,270,274,331,335,350,354,361],[11,12,13,14,18,19,23,24,27,28,31,32,35],"p",{},"Stripe (and serious equivalents) delivers webhooks ",[15,16,17],"strong",{},"at-least-once",": the same event ",[20,21,22],"code",{},"id"," can arrive twice, and distinct events may appear ",[15,25,26],{},"out of order"," relative to business time. Handlers must be ",[15,29,30],{},"idempotent"," and safe under ",[15,33,34],{},"concurrent"," delivery attempts.",[11,37,38,39,46,47,50,51,54],{},"Primary references: Stripe’s docs on ",[40,41,45],"a",{"href":42,"rel":43},"https:\u002F\u002Fdocs.stripe.com\u002Fwebhooks#duplicates",[44],"nofollow","duplicate events"," and signature verification with the endpoint signing secret (",[20,48,49],{},"Stripe-Signature","). Keep your ",[20,52,53],{},"Stripe-Version"," aligned with the server integration you tested.",[56,57,59],"h2",{"id":58},"at-least-once-semantics","At-least-once semantics",[11,61,62],{},"This implies three obligations:",[64,65,66,74,84],"ol",{},[67,68,69,70,73],"li",{},"Return ",[15,71,72],{},"2xx quickly"," after you durably store the event or enqueue it transactionally—Stripe retries on timeouts or 5xx.",[67,75,76,79,80,83],{},[15,77,78],{},"Never double-apply"," domain side effects for the same ",[20,81,82],{},"event.id",".",[67,85,86,89,90,93,94,97,98,101],{},[15,87,88],{},"Order-sensitive"," updates need discipline: ",[20,91,92],{},"customer.subscription.updated"," may follow ",[20,95,96],{},"…deleted"," during retries—use monotonic versioning or compare Stripe ",[20,99,100],{},"event.created"," under a lock.",[56,103,105],{"id":104},"minimal-table-schema","Minimal table schema",[107,108,113],"pre",{"className":109,"code":110,"language":111,"meta":112,"style":112},"language-sql shiki shiki-themes github-light github-dark","CREATE TABLE stripe_events (\n  id            text PRIMARY KEY,        -- evt_*\n  type          text NOT NULL,\n  received_at   timestamptz NOT NULL DEFAULT now(),\n  processed_at  timestamptz,\n  payload_hash  bytea\n);\n","sql","",[20,114,115,123,129,135,141,147,153],{"__ignoreMap":112},[116,117,120],"span",{"class":118,"line":119},"line",1,[116,121,122],{},"CREATE TABLE stripe_events (\n",[116,124,126],{"class":118,"line":125},2,[116,127,128],{},"  id            text PRIMARY KEY,        -- evt_*\n",[116,130,132],{"class":118,"line":131},3,[116,133,134],{},"  type          text NOT NULL,\n",[116,136,138],{"class":118,"line":137},4,[116,139,140],{},"  received_at   timestamptz NOT NULL DEFAULT now(),\n",[116,142,144],{"class":118,"line":143},5,[116,145,146],{},"  processed_at  timestamptz,\n",[116,148,150],{"class":118,"line":149},6,[116,151,152],{},"  payload_hash  bytea\n",[116,154,156],{"class":118,"line":155},7,[116,157,158],{},");\n",[11,160,161,163,164,167],{},[20,162,22],{}," is Stripe’s event id, not your internal surrogate key. ",[20,165,166],{},"processed_at"," null means pending or in-flight.",[56,169,171],{"id":170},"transactional-handler-pseudocode","Transactional handler (pseudocode)",[107,173,178],{"className":174,"code":176,"language":177,"meta":112},[175],"language-text","BEGIN;\nINSERT INTO stripe_events (id, type) VALUES ($eventId, $type)\n  ON CONFLICT (id) DO NOTHING;\nIF NOT FOUND (row inserted) THEN\n  COMMIT; RETURN 200;\nEND IF;\nINSERT INTO jobs (event_id, ...) VALUES ($eventId, ...);\nCOMMIT;\n","text",[20,179,176],{"__ignoreMap":112},[11,181,182,183,186,187,83],{},"If business logic is slow, prefer a ",[15,184,185],{},"short transaction"," that deduplicates + enqueues; a worker sets ",[20,188,166],{},[56,190,192],{"id":191},"concurrency-and-unique-constraints","Concurrency and unique constraints",[11,194,195,196,199,200,202,203,206,207,210,211,214,215,218],{},"Two instances may POST the same payload milliseconds apart. A ",[15,197,198],{},"unique"," ",[20,201,82],{}," with ",[20,204,205],{},"INSERT … ON CONFLICT"," (Postgres) or SQLite ",[20,208,209],{},"INSERT OR IGNORE"," prevents double processing. Avoid ",[20,212,213],{},"SELECT"," then ",[20,216,217],{},"INSERT"," without locking—you will race.",[56,220,222],{"id":221},"security-and-replay","Security and replay",[11,224,225],{},"Before mutating state:",[64,227,228,235,238],{},[67,229,230,231,234],{},"Verify the signature with the ",[15,232,233],{},"webhook endpoint"," secret (not your generic API key).",[67,236,237],{},"Validate the signed timestamp within Stripe’s documented tolerance.",[67,239,240],{},"Optionally reject events older than your replay window.",[56,242,244],{"id":243},"minimal-tests","Minimal tests",[246,247,248,254,264],"ul",{},[67,249,250,253],{},[15,251,252],{},"Double POST"," identical payload → one durable side effect.",[67,255,256,259,260,263],{},[15,257,258],{},"Reordered events"," via mocks → final state matches the rule you chose (e.g. latest ",[20,261,262],{},"created"," wins).",[67,265,266,269],{},[15,267,268],{},"Slow handler"," → Stripe retries; second attempt must not duplicate internal billing.",[56,271,273],{"id":272},"what-stripe-publishes-verifiable","What Stripe publishes (verifiable)",[246,275,276,300,321],{},[67,277,278,281,282,285,286,288,289,294,295,83],{},[15,279,280],{},"Retries",": failed webhook deliveries retry with backoff for ",[15,283,284],{},"up to ~3 days","—treat each ",[20,287,82],{}," as your natural idempotency key. Operational detail: ",[40,290,293],{"href":291,"rel":292},"https:\u002F\u002Fdocs.stripe.com\u002Fwebhooks\u002Fprocess-undelivered-events",[44],"Process undelivered events"," plus the overview ",[40,296,299],{"href":297,"rel":298},"https:\u002F\u002Fdocs.stripe.com\u002Fwebhooks",[44],"Receive Stripe events",[67,301,302,308,309,312,313,315,316,83],{},[15,303,304,307],{},[20,305,306],{},"constructEvent"," \u002F signatures",": official SDKs need the ",[15,310,311],{},"raw POST body"," + ",[20,314,49],{}," + the endpoint-specific secret—middleware that parses JSON before verification breaks HMAC validation. See ",[40,317,320],{"href":318,"rel":319},"https:\u002F\u002Fdocs.stripe.com\u002Fwebhooks\u002Fsignature",[44],"Resolve signature errors",[67,322,323,326,327,330],{},[15,324,325],{},"Local dev",": ",[20,328,329],{},"stripe listen --forward-to localhost:3000\u002Fwebhook"," is still the fastest way to capture realistic payloads while integrating.",[56,332,334],{"id":333},"out-of-scope","Out of scope",[11,336,337,338,341,342,345,346,349],{},"This does not cover ",[15,339,340],{},"Stripe Connect"," multi-party routing, beta ",[15,343,344],{},"thin events",", or REST ",[15,347,348],{},"Idempotency-Key"," headers on charge APIs—related but different mechanics. For non-Stripe vendors, reuse the same skeleton: stable event id + uniqueness + short transactions.",[56,351,353],{"id":352},"summary","Summary",[11,355,356,357,360],{},"Persist Stripe’s ",[15,358,359],{},"event id"," with a uniqueness guarantee before side effects; commit before responding 2xx; push heavy work to a queue. You survive duplicates, retries, and limited reordering without corrupting money or state.",[362,363,364],"style",{},"html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}",{"title":112,"searchDepth":125,"depth":125,"links":366},[367,368,369,370,371,372,373,374,375],{"id":58,"depth":125,"text":59},{"id":104,"depth":125,"text":105},{"id":170,"depth":125,"text":171},{"id":191,"depth":125,"text":192},{"id":221,"depth":125,"text":222},{"id":243,"depth":125,"text":244},{"id":272,"depth":125,"text":273},{"id":333,"depth":125,"text":334},{"id":352,"depth":125,"text":353},"\u002Fblog\u002F35_stripe_webhook_idempotency_duplicates_1x.webp","A minimal schema and transactional handler for duplicate, out-of-order, or at-least-once Stripe webhooks, without assuming each event is unique.",false,"md","en",{},true,"\u002Fen\u002Fblog\u002Fstripe-webhook-idempotency-duplicates","2026-05-20",{"title":5,"description":377},"Stripe webhooks: idempotency, duplicates","stripe-webhook-idempotency-duplicates","en\u002Fblog\u002Fstripe-webhook-idempotency-duplicates",[390],"mvp","-qb7pTBYwEZzvasPiIBXROdq68M1WJ9y_BCz4LJMmsk"]