Een publieke ontvangst-URL kan requests van iedereen ontvangen. Een aanvaller kan een vervalst event naar die URL sturen, dus het request heeft authenticatie nodig voordat het werk triggert.
Bird gebruikt het Standard Webhooks-ondertekeningsschema. Het authenticeert de event-identifier en het moment van de poging samen met de body, zodat het wijzigen van een van deze de handtekening ongeldig maakt.
Wat ondertekent Bird?
Bird ondertekent de event-identifier, het tijdstempel van de afleverpoging en de onbewerkte request-body, samengevoegd met punten.
Houd de request-body ongewijzigd totdat je de handtekening hebt geverifieerd. Het parsen en serialiseren van JSON kan de bytes veranderen die Bird heeft ondertekend.
| Header | Wat het bevat |
|---|---|
webhook-id | De event-identifier, hergebruikt bij nieuwe pogingen en replays. |
webhook-timestamp | Het moment van de poging als Unix-tijdstempel in seconden. |
webhook-signature | Een of meer handtekeningen, gescheiden door spaties. Elke begint met v1,. |
Converteer het tijdstempel van seconden voordat je het vergelijkt met een klok die milliseconden rapporteert.
Verwijder het whsec_-prefix van je endpoint-secret en base64-decodeer de rest om de sleutelbytes te verkrijgen.
Voeg de identifier, het tijdstempel en de ongewijzigde body samen met punten. Bereken HMAC-SHA256 over die string met de gedecodeerde sleutel. Vergelijk het resultaat met elke meegeleverde handtekening via een constant-time vergelijking, waarvan de looptijd niet onthult welke bytes overeenkomen.
Waarom komt mijn handtekening nooit overeen?
Een verkeerd secret of een gewijzigde request-body kan elke handtekeningcontrole laten falen.
Webframeworks parsen JSON vaak voordat je handler draait. Dat object opnieuw serialiseren kan witruimte, sleutelvolgorde of getalnotatie veranderen. De resulterende JSON kan hetzelfde betekenen maar een andere handtekening opleveren.
Configureer deze route om de onbewerkte body te bewaren. Controleer of het secret bij dit endpoint hoort, vooral na een deployment of rotatie.
Wat moet mijn handler weigeren?
Weiger een request als geen enkele handtekening overeenkomt of als het ondertekende tijdstempel buiten het toegestane tijdvenster valt.
Probeer elke handtekening in webhook-signature. Tijdens secret-rotatie bevat een aflevering handtekeningen van meerdere geldige secrets. Door elke overeenkomende handtekening te accepteren blijven ontvangers met elk van beide secrets werken.
Gebruik een tijdstempeltolerantie van vijf minuten aan beide kanten van je klok. Een onderschept request van tien minuten geleden faalt dan, zelfs als de handtekening ongewijzigd is. Houd je serverklok nauwkeurig zodat echte afleveringen niet worden geweigerd.
Controleer webhook-id tegen events die je al hebt opgeslagen. Een herkend duplicaat moet succes ontvangen zonder het werk te herhalen, omdat het opnieuw proberen van dezelfde aflevering geen nieuw event toevoegt.
Wat gebeurt er als ik een aflevering weiger?
Bird probeert een aflevering opnieuw als die een foutresponse of geen response ontvangt vóór de timeout.
Een 400-response registreert bijvoorbeeld de weigering en laat de aflevering in aanmerking komen om opnieuw te proberen. Alle niet-2xx-responses volgen het retry-beleid. De code helpt je de fout te diagnosticeren in je logs.
Het schema beslaat ongeveer 27,5 uur vóór aanpassingen, zodat je tijd hebt om een verkeerd secret te herstellen. Mislukte webhook-retries beschrijft het schema en hoe je gemiste events daarna opnieuw kunt afspelen.
Geef pas 2xx terug nadat je het event hebt geverifieerd en veilig opgeslagen, of een al opgeslagen duplicaat hebt herkend. Bird slaat geslaagde afleveringen over tijdens replay, dus het bevestigen van een niet-geverifieerd request voorkomt herstel via dat mechanisme.
Moet ik verificatie zelf implementeren?
Je hoeft verificatie niet zelf te implementeren als je webhooks.unwrap gebruikt in een Bird SDK. Geef de onbewerkte body en request-headers mee.
De helper controleert de handtekening en het tijdstempel voordat het gedecodeerde event wordt teruggegeven. Je applicatie dedupliseert nog steeds op webhook-id, omdat zij het overzicht heeft van afgerond werk.
Een compatibele Standard Webhooks-verificatiebibliotheek kan dezelfde controles uitvoeren. De webhooks-handleiding bevat voorbeelden en een handmatige implementatie.
Kort gezegd
Verifieer de oorspronkelijke bytes.
Het parsen en serialiseren van JSON kan de bytes veranderen die Bird heeft ondertekend. Bewaar de onbewerkte body voor verificatie.
Controleer ook het tijdstempel, niet alleen de handtekening.
Een tijdstempeltolerantie van vijf minuten beperkt hergebruik van onderschepte requests. Dedupliseer opgeslagen events apart op webhook-id.
Probeer elke meegeleverde handtekening.
Rotatie levert overlappende handtekeningen op. Een match met een willekeurige geldige handtekening laat de deployment doorgaan.
Bevestig alleen geverifieerde, opgeslagen events.
Bird probeert niet-2xx-responses opnieuw en slaat geslaagde afleveringen over tijdens replay. Geef succes terug voor duplicaten die al zijn opgeslagen zonder hun werk te herhalen.