[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"blog-it-stripe-webhook-idempotency-duplicates":3},{"id":4,"title":5,"author":6,"body":7,"cover":381,"description":382,"draft":383,"extension":384,"locale":385,"meta":386,"navigation":387,"path":388,"publishedAt":389,"seo":390,"seoTitle":391,"slug":392,"stem":393,"tags":394,"__hash__":396},"blog\u002Fit\u002Fblog\u002Fstripe-webhook-idempotency-duplicates.md","Webhook Stripe: idempotenza, duplicati e concorrenza","Manuel Tardivo",{"type":8,"value":9,"toc":370},"minimark",[10,36,55,60,63,101,105,158,171,175,183,193,197,212,216,219,238,242,271,275,340,344,355,359,366],[11,12,13,14,18,19,23,24,27,28,31,32,35],"p",{},"Stripe (e analoghi seri) consegna webhook ",[15,16,17],"strong",{},"at-least-once",": lo stesso ",[20,21,22],"code",{},"id"," evento può arrivare due volte, e due eventi diversi possono arrivare in ",[15,25,26],{},"ordine invertito"," rispetto alla timeline business. Il tuo handler deve essere ",[15,29,30],{},"idempotente"," e ",[15,33,34],{},"serializzabile"," rispetto alla chiave naturale dell’evento.",[11,37,38,39,46,47,50,51,54],{},"Documentazione di riferimento: ",[40,41,45],"a",{"href":42,"rel":43},"https:\u002F\u002Fdocs.stripe.com\u002Fwebhooks#duplicates",[44],"nofollow","Gestire eventi duplicati"," e verifica firma con signing secret (header ",[20,48,49],{},"Stripe-Signature","). La versione API (",[20,52,53],{},"Stripe-Version",") va allineata al tuo backend.",[56,57,59],"h2",{"id":58},"semantica-at-least-once","Semantica at-least-once",[11,61,62],{},"Implica tre obblighi:",[64,65,66,73,83],"ol",{},[67,68,69,72],"li",{},[15,70,71],{},"Rispondere 2xx rapidamente"," dopo aver persistito l’evento o averlo accodato in modo transazionale—Stripe ritenta su timeout o 5xx.",[67,74,75,78,79,82],{},[15,76,77],{},"Non applicare side-effect duplicati"," se lo stesso ",[20,80,81],{},"event.id"," viene ritentato.",[67,84,85,88,89,92,93,96,97,100],{},[15,86,87],{},"Ordinare"," gli update di stato business con cautela: ",[20,90,91],{},"customer.subscription.updated"," può arrivare dopo ",[20,94,95],{},"…deleted"," in caso di retry—usa versione monotona o confronto timestamp Stripe (",[20,98,99],{},"event.created",") con locking.",[56,102,104],{"id":103},"schema-tabella-minimo","Schema tabella minimo",[106,107,112],"pre",{"className":108,"code":109,"language":110,"meta":111,"style":111},"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,113,114,122,128,134,140,146,152],{"__ignoreMap":111},[115,116,119],"span",{"class":117,"line":118},"line",1,[115,120,121],{},"CREATE TABLE stripe_events (\n",[115,123,125],{"class":117,"line":124},2,[115,126,127],{},"  id            text PRIMARY KEY,        -- evt_*\n",[115,129,131],{"class":117,"line":130},3,[115,132,133],{},"  type          text NOT NULL,\n",[115,135,137],{"class":117,"line":136},4,[115,138,139],{},"  received_at   timestamptz NOT NULL DEFAULT now(),\n",[115,141,143],{"class":117,"line":142},5,[115,144,145],{},"  processed_at  timestamptz,\n",[115,147,149],{"class":117,"line":148},6,[115,150,151],{},"  payload_hash  bytea\n",[115,153,155],{"class":117,"line":154},7,[115,156,157],{},");\n",[11,159,160,162,163,166,167,170],{},[20,161,22],{}," è l’id ",[15,164,165],{},"Stripe"," dell’evento, non il tuo id interno. ",[20,168,169],{},"processed_at"," null = da processare o in flight.",[56,172,174],{"id":173},"handler-transazionale-pseudocodice","Handler transazionale (pseudocodice)",[106,176,181],{"className":177,"code":179,"language":180,"meta":111},[178],"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,182,179],{"__ignoreMap":111},[11,184,185,186,189,190,192],{},"Se la logica di business è lunga, pattern sicuro: ",[15,187,188],{},"transazione breve"," che deduplica + accoda; worker separato che marca ",[20,191,169],{},".",[56,194,196],{"id":195},"concorrenza-e-unique-constraint","Concorrenza e unique constraint",[11,198,199,200,203,204,207,208,211],{},"Due istanze dello stesso handler possono ricevere lo stesso POST quasi in parallelo. ",[20,201,202],{},"UNIQUE(event.id)"," + ",[20,205,206],{},"INSERT … ON CONFLICT"," (Postgres) o equivalente in SQLite (",[20,209,210],{},"INSERT OR IGNORE",") evita doppie elaborazioni. Evita “SELECT then INSERT” senza lock—race garantita.",[56,213,215],{"id":214},"sicurezza-e-replay","Sicurezza e replay",[11,217,218],{},"Prima di toccare DB:",[64,220,221,228,235],{},[67,222,223,224,227],{},"Verifica firma con secret del ",[15,225,226],{},"endpoint"," webhook (non la secret API generica).",[67,229,230,231,234],{},"Controlla ",[20,232,233],{},"timestamp"," nel payload firma contro clock skew (Stripe documenta tolleranza default).",[67,236,237],{},"Ignora eventi troppo vecchi se il dominio lo richiede (finestra anti-replay).",[56,239,241],{"id":240},"test-minimi","Test minimi",[243,244,245,255,265],"ul",{},[67,246,247,250,251,254],{},[15,248,249],{},"Doppio POST"," identico → una sola riga ",[20,252,253],{},"stripe_events"," con side-effect una tantum.",[67,256,257,260,261,264],{},[15,258,259],{},"Due eventi sequenziali invertiti"," simulati (mock) → stato finale coerente con regola scelta (es. max ",[20,262,263],{},"created"," vince).",[67,266,267,270],{},[15,268,269],{},"Timeout",": handler lento > soglia → Stripe ritenta; verifica che il secondo passaggio non raddoppi addebiti interni.",[56,272,274],{"id":273},"cosa-dice-stripe-verificabile","Cosa dice Stripe (verificabile)",[243,276,277,305,330],{},[67,278,279,282,283,286,287,289,290,293,294,299,300,192],{},[15,280,281],{},"Retry",": documentazione e prodotti webhook ritentano le consegne fallite per ",[15,284,285],{},"fino a ~3 giorni"," con backoff—tratta ogni ",[20,288,81],{}," come ",[15,291,292],{},"idempotency key"," naturale. Approfondimento operativo: ",[40,295,298],{"href":296,"rel":297},"https:\u002F\u002Fdocs.stripe.com\u002Fwebhooks\u002Fprocess-undelivered-events",[44],"Process undelivered events"," e panorama ",[40,301,304],{"href":302,"rel":303},"https:\u002F\u002Fdocs.stripe.com\u002Fwebhooks",[44],"Receive Stripe events",[67,306,307,313,314,317,318,321,322,324,325,192],{},[15,308,309,312],{},[20,310,311],{},"constructEvent"," \u002F verifica firma",": le librerie ufficiali richiedono il ",[15,315,316],{},"corpo grezzo"," (",[20,319,320],{},"raw body",") del POST + header ",[20,323,49],{}," + webhook secret dell’endpoint—middleware che parsano JSON prima della verifica rompono la firma. Riferimento: ",[40,326,329],{"href":327,"rel":328},"https:\u002F\u002Fdocs.stripe.com\u002Fwebhooks\u002Fsignature",[44],"Resolve signature errors",[67,331,332,335,336,339],{},[15,333,334],{},"CLI locale",": ",[20,337,338],{},"stripe listen --forward-to localhost:3000\u002Fwebhook"," resta il modo più rapido per catturare payload reali quando integri per la prima volta.",[56,341,343],{"id":342},"limitazioni","Limitazioni",[11,345,346,347,350,351,354],{},"Non copre ",[15,348,349],{},"Stripe Connect"," multi-account, ",[15,352,353],{},"thin events"," beta, né idempotency key sulle API di pagamento (argomento affine ma distinto).",[56,356,358],{"id":357},"sintesi","Sintesi",[11,360,361,362,365],{},"Persisti l’",[15,363,364],{},"id evento"," con vincolo unico prima di side-effect; rispondi 2xx dopo commit; sposta business lento in coda. Così sopravvivi a duplicati, retry e una dose di out-of-order senza perdita di denaro o stato.",[367,368,369],"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":111,"searchDepth":124,"depth":124,"links":371},[372,373,374,375,376,377,378,379,380],{"id":58,"depth":124,"text":59},{"id":103,"depth":124,"text":104},{"id":173,"depth":124,"text":174},{"id":195,"depth":124,"text":196},{"id":214,"depth":124,"text":215},{"id":240,"depth":124,"text":241},{"id":273,"depth":124,"text":274},{"id":342,"depth":124,"text":343},{"id":357,"depth":124,"text":358},"\u002Fblog\u002F35_stripe_webhook_idempotency_duplicates_1x.webp","Schema minimo e handler transazionale per webhook Stripe duplicati, fuori ordine o at-least-once, senza dare per scontata l'unicità dell'evento.",false,"md","it",{},true,"\u002Fit\u002Fblog\u002Fstripe-webhook-idempotency-duplicates","2026-05-20",{"title":5,"description":382},"Webhook Stripe: idempotenza e duplicati","stripe-webhook-idempotency-duplicates","it\u002Fblog\u002Fstripe-webhook-idempotency-duplicates",[395],"mvp","lma6aFHf1uYsCe8cNA_aro7fwGw7iqNBm_Ggjpu4COQ"]