Eine öffentliche Empfangs-URL kann Requests von jedem empfangen. Ein Angreifer kann ein gefälschtes Event an diese URL senden, daher muss der Request authentifiziert werden, bevor er Verarbeitung auslöst.
Bird verwendet das Standard-Webhooks-Signaturverfahren. Es authentifiziert die Event-Kennung und den Versuchszeitpunkt zusammen mit dem Body, sodass eine Änderung an einem dieser Werte die Signatur ungültig macht.
Was signiert Bird?
Bird signiert die Event-Kennung, den Zeitstempel des Zustellversuchs und den rohen Request-Body, verbunden durch Punkte.
Lassen Sie den Request-Body unverändert, bis Sie die Signatur verifiziert haben. Das Parsen und Serialisieren von JSON kann die Bytes verändern, die Bird signiert hat.
| Header | Was er enthält |
|---|---|
webhook-id | Die Event-Kennung, wiederverwendet bei Wiederholungen und Replays. |
webhook-timestamp | Der Versuchszeitpunkt als Unix-Zeitstempel in Sekunden. |
webhook-signature | Eine oder mehrere Signaturen, getrennt durch Leerzeichen. Jede beginnt mit v1,. |
Konvertieren Sie den Zeitstempel von Sekunden, bevor Sie ihn mit einer Uhr vergleichen, die Millisekunden liefert.
Entfernen Sie das Präfix whsec_ von Ihrem Endpoint-Secret und dekodieren Sie den Rest mit Base64, um die Schlüssel-Bytes zu erhalten.
Verbinden Sie die Kennung, den Zeitstempel und den unveränderten Body mit Punkten. Berechnen Sie HMAC-SHA256 über diesen String mit dem dekodierten Schlüssel. Vergleichen Sie das Ergebnis mit jeder mitgelieferten Signatur mittels eines Konstantzeit-Vergleichs, dessen Laufzeit nicht verrät, welche Bytes übereinstimmen.
Warum stimmt meine Signatur nie überein?
Ein falsches Secret oder ein veränderter Request-Body kann jede Signaturprüfung fehlschlagen lassen.
Web-Frameworks parsen JSON oft, bevor Ihr Handler ausgeführt wird. Das erneute Serialisieren dieses Objekts kann Leerzeichen, Schlüsselreihenfolge oder Zahlenformatierung verändern. Das resultierende JSON kann dasselbe bedeuten und trotzdem eine andere Signatur erzeugen.
Konfigurieren Sie diese Route so, dass sie ihren rohen Body bewahrt. Prüfen Sie, dass das Secret zu diesem Endpoint gehört, insbesondere nach einem Deployment oder einer Rotation.
Was sollte mein Handler ablehnen?
Lehnen Sie einen Request ab, wenn keine Signatur übereinstimmt oder der signierte Zeitstempel außerhalb des erlaubten Zeitfensters liegt.
Probieren Sie jede Signatur in webhook-signature. Während einer Secret-Rotation enthält eine Zustellung Signaturen von mehreren gültigen Secrets. Das Akzeptieren einer beliebigen passenden Signatur ermöglicht Empfängern mit beiden Secrets die Weiterarbeit.
Verwenden Sie eine Zeitstempel-Toleranz von fünf Minuten in beide Richtungen Ihrer Uhr. Ein abgefangener Request von zehn Minuten zuvor schlägt dann fehl, selbst wenn seine Signatur unverändert ist. Halten Sie Ihre Serveruhr genau, damit sie echte Zustellungen nicht ablehnt.
Prüfen Sie webhook-id gegen bereits gespeicherte Events. Ein erkanntes Duplikat sollte Erfolg zurückgeben, ohne seine Verarbeitung zu wiederholen, da das erneute Zustellen desselben Events kein neues Event hinzufügt.
Was passiert, wenn ich eine Zustellung ablehne?
Bird wiederholt eine Zustellung, die eine Fehlerantwort oder vor Ablauf des Timeouts keine Antwort erhält.
Eine 400-Antwort beispielsweise vermerkt die Ablehnung und lässt die Zustellung für einen erneuten Versuch offen. Alle Nicht-2xx-Antworten folgen der Retry-Richtlinie. Der Statuscode hilft Ihnen, den Fehler in Ihren Logs zu diagnostizieren.
Der Zeitplan erstreckt sich vor Anpassungen über etwa 27,5 Stunden und gibt Ihnen Zeit, ein falsches Secret zu reparieren. Fehlgeschlagene Webhook-Wiederholungen beschreibt den Zeitplan und wie Sie verpasste Events danach erneut abspielen können.
Geben Sie 2xx erst zurück, nachdem Sie das Event verifiziert und sicher gespeichert oder ein bereits gespeichertes Duplikat erkannt haben. Bird überspringt erfolgreiche Zustellungen beim Replay, sodass das Bestätigen eines unverifizierten Requests eine Wiederherstellung über diesen Mechanismus verhindert.
Muss ich die Verifizierung selbst implementieren?
Sie müssen die Verifizierung nicht selbst implementieren, wenn Sie webhooks.unwrap in einem Bird SDK verwenden. Übergeben Sie den rohen Body und die Request-Header.
Der Helper prüft Signatur und Zeitstempel, bevor er das dekodierte Event zurückgibt. Ihre Anwendung dedupliziert weiterhin anhand von webhook-id, da sie die Aufzeichnung der abgeschlossenen Verarbeitung besitzt.
Eine kompatible Standard-Webhooks-Verifizierungsbibliothek kann dieselben Prüfungen durchführen. Der Webhooks-Leitfaden enthält Beispiele und eine manuelle Implementierung.
Kurz gesagt
Verifizieren Sie die ursprünglichen Bytes.
Das Parsen und Serialisieren von JSON kann die Bytes verändern, die Bird signiert hat. Bewahren Sie den rohen Body für die Verifizierung auf.
Prüfen Sie die Zeit ebenso wie die Signatur.
Eine Zeitstempel-Toleranz von fünf Minuten begrenzt die Wiederverwendung abgefangener Requests. Deduplizieren Sie gespeicherte Events separat anhand der webhook-id.
Probieren Sie jede mitgelieferte Signatur.
Rotation erzeugt sich überlappende Signaturen. Ein Treffer gegen eine beliebige gültige Signatur ermöglicht die Fortsetzung des Deployments.
Bestätigen Sie nur verifizierte, gespeicherte Events.
Bird wiederholt Zustellungen bei Nicht-2xx-Antworten und überspringt erfolgreiche Zustellungen beim Replay. Geben Sie bei bereits gespeicherten Duplikaten Erfolg zurück, ohne deren Verarbeitung zu wiederholen.