Wie rotiere ich ein Webhook-Secret ohne Ausfallzeit?

Ihre Empfänger deployen möglicherweise zu unterschiedlichen Zeitpunkten. Eine Überlappung ermöglicht es einem Empfänger mit dem alten Secret und einem Empfänger mit dem neuen Secret, dieselbe Zustellung zu authentifizieren.

Verifizieren Sie Zustellungen während des gesamten Deployments weiter, damit eine Anfrage eines Angreifers keine Verarbeitung auslösen kann.

Was passiert, wenn ich rotiere?

Bird gibt Ihnen ein neues Signing-Secret. Deployen Sie es innerhalb von 24 Stunden, solange Bird noch mit dem alten Secret signiert.

Rufen Sie rotateWebhookSecret für Ihren Endpoint auf. Speichern Sie dessen secret, einen nicht leeren String, der mit whsec_ beginnt, denn er wird nur in dieser Antwort zurückgegeben.

Bird signiert jede Zustellung während der Überlappung mit beiden Secrets. Der webhook-signature-Header enthält durch Leerzeichen getrennte Signaturen, die jeweils mit v1, beginnen.

Ein Empfänger kann jede der Signaturen mit dem zugehörigen Secret verifizieren. Schließen Sie das Deployment innerhalb von 24 Stunden ab, da das alte Secret nach diesem Zeitfenster nicht mehr signiert.

Was muss mein Handler tun?

Ihr Handler muss eine Zustellung akzeptieren, wenn irgendeine der mitgelieferten Signaturen zu einem Secret passt, dem er vertraut.

Ein Empfänger, der nur die erste Signatur prüft, kann gültige Zustellungen ablehnen, nachdem er das Secret gewechselt hat.

Die Standard-Webhooks-Spezifikation definiert eine Liste von Signaturen, damit Empfänger während der Rotation jede einzelne prüfen können. Testen Sie Ihren Verifier mit mehreren Signaturen, bevor Sie einen produktiven Endpoint rotieren.

Behalten Sie die Timestamp- und Duplikatprüfungen während der gesamten Änderung bei. Signaturverifizierung beschreibt diese Prüfungen.

Was ist die sichere Reihenfolge?

Speichern und deployen Sie das neue Secret. Bestätigen Sie die Verifizierung, bevor die Überlappung des alten Secrets endet.

1. Rotieren Sie das Endpoint-Secret und speichern Sie den zurückgegebenen Wert sofort.
2. Deployen Sie den neuen Wert innerhalb der 24-stündigen Überlappung auf jede Empfängerinstanz.
3. Bestätigen Sie, dass Empfänger Zustellungen mit dem neuen Secret verifizieren, anhand von Empfänger-Logs und den Zustellversuchen von Bird.
4. Lassen Sie das vorherige Secret nach der Überlappung automatisch ablaufen.

Es gibt keinen separaten Entfernungsschritt in der Rotation. Wenn das alte Secret kompromittiert wurde, vertrauen Sie ihm in Ihren Empfängern nicht mehr, sobald diese das neue haben. Rotation allein lässt Empfänger, die dem alten Secret vertrauen, während der Überlappung angreifbar.

Was passiert, wenn ich sofort erneut rotiere?

Eine weitere Rotation kann gelingen, bis der Endpoint fünf gleichzeitig gültige Secrets erreicht.

Ausgehend von einem Secret können vier Rotationen diese fünf Plätze füllen, bevor ältere Secrets ablaufen. Die nächste Rotation schlägt mit WebhookTooManySecrets fehl. Eine Rotationsschleife kann daher verhindern, dass ein neues Secret ausgestellt wird, wenn Sie es brauchen.

Warten Sie, bis ein älteres Secret abgelaufen ist, bevor Sie erneut rotieren. Wiederholte Rotation beseitigt nicht die Notwendigkeit, das neue Secret auf Ihren Empfängern zu deployen.

Was passiert mit Zustellungen, die während der Änderung fehlgeschlagen sind?

Bird wiederholt fehlgeschlagene Zustellungen, sodass eine reparierte Verifizierung sie innerhalb des Retry-Fensters wiederherstellen kann.

Der Zeitplan umfasst vor Zeitanpassungen rund 27,5 Stunden. Eine fehlgeschlagene Zustellung kann nach Abschluss der Retries auch per Replay wiederhergestellt werden; fehlgeschlagene Webhook-Retries erläutert das Replay-Fenster.

Geben Sie einen Fehler für eine Anfrage zurück, die Sie nicht verifizieren können. Die Rückgabe von 2xx markiert die Zustellung als erfolgreich und schließt sie vom Replay verpasster Events aus.