Je ontvangers deployen mogelijk op verschillende momenten. Een overlap zorgt ervoor dat een ontvanger met het oude secret en een ontvanger met het nieuwe secret dezelfde aflevering kunnen verifiëren.
Blijf afleveringen verifiëren gedurende de hele deployment, zodat een verzoek van een aanvaller geen werk kan triggeren.
Wat gebeurt er als ik roteer?
Bird geeft je een nieuw signing secret. Deploy het binnen 24 uur, terwijl Bird nog met het oude secret ondertekent.
Roep rotateWebhookSecret aan voor je endpoint. Sla het secret op, een niet-lege string die begint met whsec_, want het wordt alleen in dat antwoord teruggegeven.
Bird ondertekent elke aflevering met beide secrets tijdens de overlap. De webhook-signature-header bevat door spaties gescheiden handtekeningen, elk beginnend met v1,.
Een ontvanger kan beide handtekeningen verifiëren met het bijbehorende secret. Rond de deployment af binnen 24 uur, want het oude secret stopt met ondertekenen na dat venster.
Wat moet mijn handler doen?
Je handler moet een aflevering accepteren zodra een meegeleverde handtekening overeenkomt met een secret dat hij vertrouwt.
Een ontvanger die alleen de eerste handtekening controleert, kan geldige afleveringen weigeren nadat hij van secret wisselt.
De Standard Webhooks-specificatie definieert een lijst met handtekeningen zodat ontvangers ze allemaal kunnen proberen tijdens rotatie. Test je verifier met meerdere handtekeningen voordat je een live endpoint roteert.
Houd de timestamp- en duplicaatcontroles actief gedurende de hele wijziging. Handtekeningverificatie behandelt die controles.
Wat is de veilige volgorde?
Sla het nieuwe secret op en deploy het. Bevestig verificatie voordat de overlap van het oude secret eindigt.
- Roteer het endpoint-secret en sla de teruggegeven waarde meteen op.
- Deploy de nieuwe waarde naar elke ontvanger-instantie binnen de 24-uurs overlap.
- Bevestig dat ontvangers afleveringen verifiëren met het nieuwe secret, via ontvangerlogs en de afleveringspogingen van Bird.
- Laat het vorige secret automatisch verlopen na de overlap.
Er is geen aparte verwijderstap in de rotatiebewerking. Als het oude secret is blootgesteld, stop dan met het vertrouwen ervan in je ontvangers zodra ze het nieuwe hebben. Alleen roteren laat ontvangers die het oude secret vertrouwen kwetsbaar tijdens de overlap.
Wat als ik meteen opnieuw roteer?
Een nieuwe rotatie kan slagen totdat het endpoint vijf gelijktijdig geldige secrets bereikt.
Met één secret vullen vier rotaties die vijf plekken voordat oudere secrets verlopen. De volgende rotatie mislukt met WebhookTooManySecrets. Een rotatielus kan er dus voor zorgen dat er geen nieuw secret kan worden uitgegeven wanneer je het nodig hebt.
Wacht tot een ouder secret verloopt voordat je opnieuw roteert. Herhaald roteren neemt niet de noodzaak weg om het nieuwe secret naar je ontvangers te deployen.
Wat gebeurt er met afleveringen die zijn mislukt tijdens de wijziging?
Bird probeert mislukte afleveringen opnieuw, dus het herstellen van verificatie kan ze terugwinnen binnen het retry-venster.
Het schema beslaat ongeveer 27,5 uur vóór timingaanpassingen. Een mislukte aflevering kan ook worden hersteld via replay nadat de retries zijn afgelopen; mislukte webhook-retries legt het replay-venster uit.
Geef een fout terug voor een verzoek dat je niet kunt verifiëren. 2xx teruggeven markeert de aflevering als geslaagd, waardoor deze wordt uitgesloten van replay van gemiste events.
Kort gezegd
Deploy tijdens de overlap.
Bird ondertekent 24 uur lang met het oude en het nieuwe secret, zodat ontvangers tijd hebben om de nieuwe waarde over te nemen.
Accepteer elke overeenkomende handtekening.
Een ontvanger die alleen de eerste handtekening controleert, kan een geldige aflevering weigeren tijdens de rotatie.
Sla het nieuwe secret meteen op.
Het rotate-antwoord is de enige plek waar het nieuwe secret wordt teruggegeven.
Rotatie heeft een limiet van vijf secrets.
Met één geldig secret vullen vier rotaties de beschikbare plekken totdat een ouder secret verloopt.