Spring til indhold
SaaSIndsigter

Webhook-retries uden dobbelt opkrævning

I har håndteret retry, når det samme event-id kun kan opkræve én gang — også når Stripe sender igen.

Stripe webhook retries er det samme event to gange. Uden idempotency og et job I ejer, er retry en anden opkrævning — ikke en anden chance.

13 minutters læsning
Stiliseret SaaS-diagram: en webhook der lander to gange ved den samme hændelse, og et ledger-felt der kun lader den første skrive adgang.

SaaS & billing

Hvis I søger efter stripe webhook retries, eller efter webhook idempotency, står I typisk ét sted: en kunde er blevet opkrævet to gange, en adgang er slået til to gange, eller en faktura er sendt to gange, og nogen har sagt at 'Stripe sendte webhooken to gange'. Billing-indlægget er org-modellen, Customer Portal og det I skal have på plads før første betalende. Rate-limit-indlægget er loftet på det dyre kald. Transaktionsmail-indlægget er DNS og om mailen lander. Den her er replay. Stripe — og de fleste PSP'er — leverer mindst én gang. En retry er ikke en ny betaling. Det er det samme event, I ikke svarede 2xx på, eller som netværket tabte. Uden et event-id I gemmer, før I rører penge eller adgang, er retry en anden opkrævning, I kalder uheld.

Et webhook-endpoint der 'behandler det, der kommer ind', er ikke et system. Det er en sideeffekt med en URL. Stripe sender igen, når I svarer 5xx, når I timeout'er, når I svarer 2xx for sent. I sender selv igen, når I har et job der fejlede. Kontrakten er at-least-once. Den ærlige sætning er: det her event kan lande to gange, og anden gang skal være et nej, I allerede har gjort det. Uden den sætning har I et endpoint. I har ikke idempotency.

TL;DR

De vigtigste pointer

  • En retry er det samme event. Uden at gemme event-id'et først, er anden gang en ny opkrævning I har bedt om.
  • Svar 2xx først når I har registreret eventet. Et 200 før ledgeren er hvordan I mister hændelsen. Et 500 efter I har opkrævet er hvordan I opkræver igen.
  • Idempotency er en række I ejer — event.id, processed_at — ikke et håb om at Stripe 'nok kun sender én gang'.
  • Opfyldelse (adgang, mail, faktura) læser ledgeren. Den opretter ikke et nyt PaymentIntent, fordi webhooken 'måske fejlede'.
  • Billing-indlægget er org og portal. Rate-limit er loftet. Mail er levering. Den her er replay uden dobbelt sideeffekt.
  • I har håndteret retry, når I kan sige: det her event-id kan kun vinde én gang. Ikke når endpointet 'virker i test'.

Hvorfor det her overhovedet er vigtigt

Et SaaS der tænder adgang i webhooken og kalder det færdigt, har ikke 'simpelt billing'. Det har et race. Stripe sender `invoice.paid`. I slår et flag. I svarer 500, fordi mailen fejlede. Stripe sender igen. I slår flaget igen — eller værre, I opretter en ny charge, 'så kunden ikke hænger'. Kunden hænger ikke. Kunden er opkrævet to gange. Supporten kalder det Stripe. Det er jeres handler, der ikke havde et hukommelse.

Teams gør det, fordi den første happy path virkede. Checkout Session completed. Adgang tændt. Mail sendt. Testen var én request. Ingen replay. Ingen timeout. Ingen 'vi svarede 200 og crashede bagefter'. Tre betalende kunder senere lander et event to gange på tre minutter, og I opdager at entitlement-tabellen ikke har en unik nøgle på stripe_event_id. I retter den ene kunde. I rører ikke vanen.

Skaden er konkret. Dobbelt opkrævning I skal refundere i panik. Dobbelt periode lagt på et abonnement. To velkomstmails. To provisioneringer af et workspace. Et kreditnota-show I kalder 'Stripe var nede'. Stripe var ikke nede. Stripe gjorde det, dokumentationen siger: send igen, indtil I svarer succes. I svarede ikke succes, eller I svarede succes uden at have skrevet eventet ned. Begge er jeres job.

Vi skriver det, fordi 'vi har webhooks' er blevet et tjek, I sætter når URL'en er i Dashboard. Et ærligt setup er kedeligt: gem event.id, afvis dubletten, anvend sideeffekten én gang, svar 2xx når ledgeren kender rækken. Uden det har I et endpoint, der gør det rigtige første gang. Første gang er ikke kontrakten.

Hvad en webhook-retry faktisk er — og hvad et endpoint ikke er

En webhook-retry er den samme hændelse, leveret igen. Stripe, Adyen, Quickpay, jeres eget interne bus — samme kontrakt: mindst én gang. Eventet har et id. Id'et er den idempotency-nøgle, I ikke må finde på selv, når udbyderen allerede har én. Gem den. Hvis rækken findes, er I færdige. Hvis den ikke findes, indsæt den og kør jobbet. Forskellen er ikke om I 'håndterer webhooks'. Forskellen er om anden levering er et no-op.

Det er ikke det samme som 'vi verificerer signaturen'. Signaturen siger at payloaden er fra Stripe. Den siger ikke at I ikke har set eventet før. I kan verificere korrekt og stadig opkræve to gange. Billing-indlægget er Customer, Subscription og org. Her er at nægte at lade et gyldigt, signeret event være en ny forretningshændelse, bare fordi det landede igen.

Det er heller ikke det samme som Stripe Idempotency-Key på jeres udgående kald. Den nøgle er når I opretter et PaymentIntent og netværket er usikkert. Den hører hjemme på POST til Stripe. Webhook-retry er den anden retning: Stripe kalder jer. To nøgler, to jobs. At sætte Idempotency-Key på checkout og glemme event-id i handleren er at låse den ene dør og lade den anden stå åben.

Og det er ikke 'vi svarer altid 200, så de stopper med at sende'. Et 200 før I har skrevet eventet, er at bede Stripe om at tie. Hvis processen dør efter 200, kommer eventet ikke igen. Adgangen bliver aldrig tændt. I har byttet dobbelt opkrævning for en stille miss. Det ærlige svar er: skriv rækken (eller den midlertidige 'modtaget') i samme transaktion som I tør love 2xx. Fejl efter det er et job I retrier selv — ikke et nyt Stripe-event I håber på.

Det der typisk går galt, når nogen siger webhooken er sat op

Den første fejl er at opfylde i handleren uden en unik række. I tænder is_pro, I sender mail, I kalder provision. Eventet kommer igen. I tænder, sender, provisionerer igen. Unik nøgle på user_id er ikke nok — samme bruger kan have to ægte events. Nøglen er event.id. User_id er hvem. Event.id er hvilken hændelse. Rate-limit-indlægget er hvor ofte nogen må kalde jer. Her er at den samme kalder med den samme krop ikke må tælle som to forretninger.

Den anden fejl er at oprette en ny betaling, fordi webhooken 'fejlede'. invoice.payment_failed er ikke et signal til at køre PaymentIntent.create. Det er et signal til at vise kunden en ærlig tilstand og lade Stripe retry'e indkrævningen efter den politik, I har sat i Billing. En handler der 'fixer' et failed event ved at charge igen, er en dobbelt opkrævning med et navn, I kalder recovery.

Den tredje fejl er at blande event-typer til samme sideeffekt. checkout.session.completed og invoice.paid og payment_intent.succeeded kan alle se ud som 'de har betalt'. Hvis I tænder adgang på alle tre uden et ledger-tjek, har Checkout og den første faktura tændt to gange — eller Checkout og et senere invoice.paid har forlænget en periode, I allerede havde givet. Vælg én kilde til 'betalende'. De andre er audit. Billing-indlægget er hvilken model I vælger. Her er at én hændelse ejer opfyldelsen.

Den fjerde fejl er at svare 2xx fra et CDN eller en middleware, før jeres kode har kørt, eller at svare 500 på et event I ikke kender og dermed bede om evig retry af noget, I aldrig vil kunne anvende. Ukendt type: log, gem, 2xx. Kendt type, midlertidig fejl: 5xx, og handleren er idempotent. Kendt type, permanent (signatur, parse): 4xx, og I har et alarm. Et 500 på 'vi kender ikke typen' er at fylde retry-køen med støj, indtil Stripe giver op — og så har I mistet de events, I faktisk skulle have.

Idempotent handler vs. 'vi kører det, der kommer ind'

Det ærlige replay

Event.id i en unik række. Sideeffekt én gang. 2xx når ledgeren kender hændelsen.

  • Insert-ignore på event.id før adgang, mail eller charge
  • Opfyldelse læser ledgeren — opretter ikke et nyt PaymentIntent 'for en sikkerheds skyld'
  • 2xx efter rækken findes; 5xx kun på midlertidig fejl i et job, der tåler replay
  • Er kedeligt i test: anden request gør ingenting. Det er hele pointen

Det håbede endpoint

URL i Dashboard, happy path i klik, og retry er 'Stripe der spammede os'.

  • Adgang tændes per request, uden unik nøgle på eventet
  • Failed webhook 'fixes' med en ny charge
  • 200 sendes før databasen, eller 500 sendes efter opkrævningen
  • Er et uheld, I kalder Stripe. Kunden kalder det to træk på kortet
stripe-webhook-idempotent.tsts
// Rigtigt: event.id vinder én gang. Retry er et no-op med 2xx.
async function onStripeEvent(event: { id: string; type: string }) {
  const inserted = await db.stripeEvents.insertIgnore({ id: event.id, type: event.type });
  if (!inserted) return; // already applied
  await applyFromLedger(event); // never PaymentIntent.create "because retry"
}

// Forkert: anden levering er en ny forretningshændelse
async function onStripeEventNaive(event: { id: string }) {
  await stripe.paymentIntents.create({ /* ny opkrævning — retry er nu en anden betaling */ });
}

Sådan gør I retry til det samme event — før I tænder adgang

Uden den her rækkefølge får I endnu et endpoint, I kalder billing.

  1. 01

    Gem event.id i samme database som adgangen, med unik nøgle

    Ikke en cache, der kan glemmes. Ikke 'vi tjekker Stripe bagefter'. En række der enten indsættes eller allerede findes. Hvis I ikke kan pege på tabellen, har I ikke idempotency. I har et håb om at netværket er pænt.

  2. 02

    Vælg én event-type der ejer opfyldelsen

    Typisk invoice.paid eller checkout.session.completed — ikke begge som 'tænd pro'. De andre typer er log og tilstand. Billing-indlægget er abonnementet. Her er at to gyldige events ikke er to ordrer.

  3. 03

    Svar 2xx når rækken er jeres, ikke når HTTP-kaldet startede

    Skriv først. Svar bagefter. Midlertidig fejl efter insert: jeres job retrier sideeffekten, Stripe skal ikke. Et 500 efter charge er den dobbelte opkrævning, I vil undgå. Et 200 før insert er den stille miss, I ikke opdager før kunden skriver.

  4. 04

    Lad aldrig handleren oprette en ny betaling 'fordi den første fejlede'

    Stripe retrier indkrævning på abonnementer efter den politik, I har sat. Jeres job er at spejle tilstanden. PaymentIntent.create i en webhook på et betalingsevent er at opkræve uden at kunden trykkede. Transaktionsmail-indlægget er kvitteringen. Her er at kvitteringen ikke må blive til et andet træk.

  5. 05

    Replay med Stripe CLI og med et gemt event-id, før I kalder det færdigt

    Send det samme event to gange. Anden gang skal I se et no-op og et 2xx. Første gang skal I se én række, én adgang, én mail. Hvis anden gang ligner første, er I ikke færdige. I har et endpoint, der virker i den test, I ikke kørte.

“I har håndteret retry, når det samme event-id kun kan opkræve én gang — også når Stripe sender igen.”

Checkout, faktura, failed og mail — samme ord, fire jobs

Checkout.session.completed er det job, I typisk tænder adgang på i et MVP. Det er fint, hvis det er den eneste kilde, og hvis session.id / event.id er unikt gemt. Det rådner, når I også tænder på invoice.paid for den samme session, eller når I opretter et abonnement i handleren og lader det første invoice.paid tænde igen. Vælg. Checkout er 'de betalte her'. Faktura er 'perioden er betalt'. De er ikke synonymer.

invoice.paid er det job, et abonnement lever på. Hver betalte periode er et event. Unik på event.id, ikke på customer-id. Et customer-id der 'allerede er pro' er ikke et no-op — næste måned er et nyt event, der skal forlænge, ikke ignoreres. Omvendt er retry af samme invoice.paid ikke en ny periode. Ledgeren skelner. Et flag på brugeren skelner ikke.

invoice.payment_failed og payment_intent.payment_failed er det job, I ikke må 'fixe' med en ny charge. Vis tilstanden. Send den mail, transaktionsmail-indlægget handler om. Lad Stripe retry'e efter jeres Billing-indstillinger. En intern 'vi trækker igen nu' fra webhooken er et andet produkt, I har gemt i en fejl-handler. Rate-limit-indlægget er hvor ofte nogen må ramme jer. Her er at I ikke rammer kunden igen, fordi I ramte jer selv.

Mail og provisionering er det job, der får jer til at svare 500 efter I har opkrævet. Skill dem. Eventet er registreret. Adgangen er tændt. Mailen er et job med egen retry. Hvis mailen fejler, er det ikke Stripes event der skal landes igen. Det er jeres kø. Et 500 her er at bede om en anden opkrævning, fordi Sendgrid var langsom. Det er den forkerte knap.

Hvad I typisk bør gøre i den situation, I står i

Venstre er det, I typisk siger. Højre er det næste skridt, vi typisk anbefaler.

  • Situation

    Kunden er opkrævet to gange efter 'Stripe sendte webhooken to gange'

    Næste skridt

    Stop med at opfylde per request. Unique på event.id. Refundér den anden. Replay to gange i test før I kalder det lukket

  • Situation

    Handleren opretter PaymentIntent, når et failed-event lander

    Næste skridt

    Fjern create. Spejl tilstanden. Lad Stripe retry'e indkrævningen. Failed er ikke et signal til at trække igen selv

  • Situation

    Både checkout.session.completed og invoice.paid tænder is_pro

    Næste skridt

    Én type ejer opfyldelsen. Den anden er audit. To gyldige events er ellers to tændinger

  • Situation

    I svarer 200 i starten af handleren 'så Stripe er glad'

    Næste skridt

    Skriv event-rækken først. 2xx bagefter. Et tidligt 200 er en miss, I ikke får tilbage

  • Situation

    I svarer 500 når mailen fejler, efter adgangen er tændt

    Næste skridt

    Mail er jeres job med egen retry. 2xx på eventet. 500 her er den anden opkrævning, I vil undgå

Tjekliste før I kalder webhooken idempotent

Hvis I mangler flere af punkterne, er sætningen webhooken er sat op — setup'et er et endpoint, I håber på.

  • I kan pege på en unik række for event.id i samme database som adgangen
  • Anden levering af samme event er et no-op med 2xx — I har set det i replay, ikke i et håb
  • Ingen PaymentIntent.create eller ny charge inde i handleren 'fordi det fejlede'
  • Én event-type ejer opfyldelsen. De andre spejler eller logger
  • 2xx betyder rækken er jeres. Mail og provision er egne jobs, ikke Stripes retry
  • Billing-indlægget er org og portal. Rate-limit er loftet. Mail er levering. Den her er replay

Spørgsmål vi får igen og igen

  • Er det her det samme som Stripe billing og org-auth, eller som rate limiting?

    Nej. Billing-indlægget er Customer, Subscription, organisation og hvem der må hvad i produktet. Rate-limit-indlægget er loftet på login, søgning og dyre kald — hvor ofte nogen må ramme jer. Transaktionsmail er om kvitteringen lander. Den her er replay: det samme event to gange, uden at anden gang bliver en ny opkrævning. I kan have en pæn org-model og stadig tænde adgang to gange. I kan have et loft på endpointet og stadig oprette to charges. De er fire jobs. Det ene erstatter ikke de andre.

  • Skal vi svare 200 med det samme, så Stripe ikke retrier?

    Kun når I har registreret eventet. Et tidligt 200 er at bede dem om at tie, før I ved om I kan anvende det. Timeout efter 200 er en miss I ikke får igen. Skriv rækken, svar 2xx, retrier sideeffekter selv. Et 5xx er rigtigt når I endnu ikke har rækken og fejlen er midlertidig — og kun hvis handleren tåler at køre igen. Målet er ikke at stoppe retries. Målet er at retries er ufarlige.

  • Er Stripe Idempotency-Key nok?

    Den er nok til jeres udgående POST til Stripe: samme nøgle, samme PaymentIntent, selv om netværket duplikerer kaldet. Den er ikke nok til webhooken ind. Indgående events har event.id. Det er den nøgle, I gemmer. To retninger, to nøgler. At sætte headeren på checkout og glemme tabellen på webhooken er at låse den dør, I selv åbner, og lade den dør Stripe banker på, stå åben.

  • Hvad med Quickpay, Adyen eller et hjemmestrikket webhook?

    Jobbet er det samme: et id I ikke selv finder på, en unik række, sideeffekt én gang, 2xx når rækken er jeres. Navnet på feltet skifter. Kontrakten skifter ikke. Hvis udbyderen ikke har et event-id, hasher I det I har (udbyder, type, forretningsnøgle) og behandler hashen som id — og I er ærlig om at et felt, I selv har valgt, er svagere end et id, udbyderen garanterer. Opfind ikke et timestamp som nøgle. Timestamp er ikke identitet.

  • Må vi refundere automatisk, hvis vi opdager en dublet charge?

    En dublet I har skabt, skylder I at rette. Automatisk refund på 'vi så eventet to gange' er farligt, hvis I ikke kan skelne replay fra to ægte betalinger. Ledgeren skelner: samme event.id er replay; to event-id'er er to hændelser. Refundér replay-skaden I har lavet. Lad være at refundere den anden ægte periode, fordi I blev forskrækket. Support uden ledger er gætværk. Gætværk på penge er den næste dublet.

Hvis retry er blevet en anden opkrævning, I kalder Stripe

Lad os skille et kedeligt event-id fra et endpoint, I håber på.

En unik række slår en handler, der gør det rigtige første gang og det forkerte anden.

Hvorfor vi skrev den her

Det er sådan vi tænker — og det er det vi bygger.

Vores indsigter handler om det vi rent faktisk leverer. Hvis det her ramte noget du arbejder med, så er der en konkret service der ligger tæt på.