Betrouwbare webhooks: evenementen ondertekenen, opnieuw afspelen en ontdubbelen

Tijdens een implementatie arriveert er om 02:14 uur een betalingswebhook. De app reageert 503. De provider probeert het nog drie keer. In de ochtend heeft de klant drie actieve abonnementen en slechts één factuur. Niemand had idempotence geïmplementeerd – alleen een naïeve ‘INSERT’.

Webhooks zijn geen ‘coole HTTP-callbacks’. Dit zijn minstens één keer bezorgen met nieuwe pogingen, niet-gegarandeerde bestelling en soms minutenlange vertraging.

Leveringsmodel

Ga ervan uit dat ten minste één keer: normale duplicaten zijn. Soms niet-FIFO-bestelling tussen gebeurtenistypen. Uw handler moet idempotent zijn en logische herschikking tolereren (bijvoorbeeld 'geannuleerd' voordat 'betaald' zeldzaam maar mogelijk).

Handtekening en tijdstempel

Controleer HMAC-SHA256 met draaibaar geheim. Weigeren als tijdstempel > 5 min (herhaling). Vergelijkingen in constante tijd voor ondertekening.

Registreer mislukte handtekeningen afzonderlijk van de 500 applicaties. Verwar een aanval niet met een bug.

Idempotentie in de praktijk

Combineer providersleutel + unieke SQL-beperking.

HTTP- en asynchrone antwoorden

Verwerking < 2 s: 200 synchronisatie. Anders 202 + staart (Redis, SQS, Konijn). De werker neemt event_id. Doe nooit zwaar werk voordat u vrijspreekt zonder idempotentie.

Wachtrij met dode letters voor bedrijfsfaillissementen na N pogingen.

Waarneembaarheid

Statistieken: handlerlatentie, 2xx/4xx/5xx-snelheid, wachtrijvertraging, overgeslagen duplicaten. Gecorreleerde tracering event_id → taak → factuur. Runbook: “handmatige herhaling zonder dubbel effect” gedocumenteerd.

Controlelijst voor eindpuntproductie

• [ ] HMAC-handtekening constant geverifieerd
• [ ] Tijdstempel anti-herhaling (<5 min)
• [ ] Unieke beperking tabel event_id
• [ ] Antwoord 2xx/202 < time-outprovider
• [ ] Asynchrone wachtrij voor verwerking >2 s
• [ ] Dode letter na N bedrijfsfaillissementen
• [ ] Gestructureerde logboeken event_id + latentie
• [ ] Idempotentie getest (3 identieke POST's)
• [ ] Firewall IP-provider gedocumenteerd
• [ ] Runbook-herhalingshandleiding zonder dubbel effect
• [ ] Geplande rotatie van webhookgeheimen
• [ ] AVG: beperkt behoud van payload

Controleer deze lijst voordat u de openbare URL openbaar maakt: een ‘bijna goede’ webhook kost meer dan een releasevertraging van twee dagen.

Speel scenario's en incidenten opnieuw af

Stel je een implementatie voor waarbij PHP-FPM dertig seconden lang opnieuw wordt opgestart: de betalingsprovider verzendt vijf gespreide nieuwe pogingen. Zonder een idempotentietabel crediteert u dezelfde betaling vijf keer. Klantenondersteuning ontdekt de bug voordat uw applicatie zich registreert, omdat het boekhouddashboard sneller duplicaten verzamelt dan uw technische monitoring.

Een legitieme herhaling verschilt van een kwaadwillige herhaling: de eerste komt van de provider na een time-out, de tweede van een aanvaller die een niet-ondertekende webhook-URL vastlegt (als je HMAC bent vergeten). De handtekening bindt het lichaam aan het geheim; zonder dit is het opnieuw afspelen van een vastgelegde POST voldoende.

Gebruik voor tests de herhalingstool van de provider (Stripe CLI, GitHub herlevering) in enscenering met een wegwerpbare basis. Controleer of de derde identieke nieuwe poging niets aan de basis verandert. Automatiseer deze test in CI als het eindpunt cruciaal is.

Aan de gedeelde hostingkant vinkt u max_execution_time PHP en nginx proxy timeout aan - een 504-gateway genereert nieuwe pogingen, zelfs als uw handler twee seconden later klaar zou zijn. Time-outs uitlijnen: nginx > PHP > provider webhook time-out, met marge.

Providers verschillen van mening over de handtekeningkop (Stripe-Signature, X-Hub-Signature-256, enz.) - verpak de verificatie per adapter, en kopieer en plak het document niet één keer.

Versie van het webhookgeheim als wachtwoord: rotatie met dubbel geheim actief gedurende 24 uur als de provider dit ondersteunt.

Belastingstest: simuleer 10× burst-webhooks – wachtrijdiepte en aantal werknemers vóór Black Friday.

Houd een gedateerd runbook bij, voor/na-statistieken en beoordeling na incidenten: cumulatieve discipline voorkomt paniek op vrijdagavond.

Houd een gedateerd runbook bij, voor/na-statistieken en beoordeling na incidenten: cumulatieve discipline voorkomt paniek op vrijdagavond.

Gedeelde time-outs

Lijn nginx> PHP> time-outprovider uit - 504 activeert nieuwe pogingen.

Beslis en ga vooruit zonder blinde vlek

1. Controleer de HMAC-handtekening in constante tijd met een anti-herspeeltijdstempel van minder dan vijf minuten.
2. Ontdubbelen op event_id — unieke beperking in basis, idempotence getest met drie identieke POST's.
3. Antwoord 2xx/202 snel — asynchrone wachtrij als de verwerking langer duurt dan twee seconden; dode letter na N bedrijfsfaillissementen.
4. Documentprovider-IP's: firewall, geheime rotatie van webhook, handmatig afspelen van runbook zonder dubbel effect.
5. Beperk het behoud van de lading — AVG-naleving van opgeslagen lichamen.

Om betrouwbare API-hosting (latency, SLA) te kiezen, gebruikt u de vergelijker, de overzicht en onze gidsen observatiemogelijkheden.

Veelgestelde vragen

Waarom webhooks ondertekenen?

De handtekening van de HMAC bewijst dat het lichaam afkomstig is van de leverancier en tijdens het transport niet is gewijzigd. Zonder dit kan iedereen POSTen naar uw eindpunt.

Welke HTTP-code voor nieuwe pogingen?

2xx vrijgesproken. 4xx kan niet opnieuw worden geprobeerd bij permanente fout (ongeldige handtekening). 5xx of time-out triggeren nieuwe pogingen - vandaar verplichte idempotence.

Hoe ontdubbelen?

Bewaar event_id (of stabiele hash) met unieke beperking; negeer reeds verwerkte duplicaten, zelfs als de hoofdtekst enigszins verschilt.

Time-out aan zenderzijde?

Vaak 5–30 sec. Reageer snel (202 + async-taak) als de verwerking lang duurt, maar garandeer dan idempotence aan de kant van de werknemer.

Simuleer drie identieke POST's voordat u het eindpunt in prod opent. Als de database drie keer verandert, bent u nog niet klaar.