Was ist ein Webhook?

Wenn Bird Ihren Endpunkt aufruft, muss der Empfänger das Ereignis sichern, bevor die Verarbeitung beginnt. Ein Webhook ist eine HTTP-Anfrage, die ein System an Ihre Anwendung sendet, wenn etwas passiert. Der Absender signiert die POST an Ihre registrierte URL. Ihr Empfänger entscheidet, wann das Ereignis dauerhaft angenommen ist.

Wie unterscheidet sich ein Webhook vom Polling einer API?

Polling bedeutet, dass Ihre App eine API nach einem Zeitplan aufruft und auf Änderungen prüft. Ein Webhook kehrt diese Richtung um: Der Anbieter ruft Ihren Endpunkt auf, wenn ein Ereignis eintritt, sodass Sie leere Anfragen vermeiden und schneller reagieren.

Webhooks benötigen einen öffentlichen HTTPS-Endpunkt, der Anfragen empfangen kann, während Ereignisse zugestellt werden. Polling funktioniert von überall und lässt Ihre App entscheiden, wann sie den Zustand abruft. Verwenden Sie Webhooks für zeitnahe Benachrichtigungen. Verwenden Sie die API, um mehr Ressourcendetails abzurufen, wenn ein Ereignis nur Bezeichner enthält.

Wie sieht eine Webhook-Anfrage aus?

Eine Webhook-Anfrage ist ein HTTP POST mit Headern und einem JSON-Ereignisumschlag. Das E-Mail-Zustellungsereignis von Bird enthält type, einen Ereignis-timestamp und typspezifische data:

{
  "type": "email.delivered",
  "timestamp": "2026-06-10T14:30:00Z",
  "data": {
    "email_id": "em_01krdgeqcxet5s7t44vh8rt9mg",
    "recipient_id": "er_01krdgeqcxet5s7t44vh8rt9mg",
    "workspace_id": "ws_01krdgeqcxet5s7t44vh8rt9mg",
    "recipient": "user@example.com",
    "recipient_role": "to",
    "tags": [{ "name": "category", "value": "welcome" }],
    "metadata": { "order_id": "ord_123" },
    "broadcast_id": null
  }
}

Die Nachrichten-ID ist data.email_id. Die Zustellungsidentität ist der webhook-id-Header, der gleich bleibt, wenn Bird dieses Ereignis erneut versucht oder wiedergibt. Der Body-timestamp zeichnet auf, wann das Ereignis eingetreten ist. Der webhook-timestamp-Header zeichnet diesen Zustellversuch auf, sodass die beiden Zeitstempel unterschiedliche Fragen beantworten. Die E-Mail-Ereignisfelder beschreiben die ereignisspezifischen Payloads.

Wie verifizieren Sie eine Webhook-Signatur?

Bewahren Sie die rohen Anfrage-Bytes auf und verifizieren Sie die Signatur, bevor Sie das Ereignis parsen oder speichern. Birds SDK prüft die Header webhook-id, webhook-timestamp und webhook-signature. Die Zeitstempel-Toleranz wird dabei automatisch angewendet. Verwenden Sie die Signatur-Anleitung, anstatt einen zweiten Verifier zu schreiben.

Wenn Sie die Signatureingabe verstehen müssen: Bird verwendet {webhook-id}.{webhook-timestamp}.{raw request body}. Das Endpunkt-Secret beginnt mit whsec_; entfernen Sie dieses Präfix und base64-decodieren Sie den Rest, bevor Sie HMAC-SHA256 berechnen. Während einer Secret-Rotation kann der Signatur-Header mehrere durch Leerzeichen getrennte v1,-Werte enthalten. Akzeptieren Sie daher einen passenden Wert aus den aktiven Secrets.

Weisen Sie fehlerhafte, nicht authentifizierte oder veraltete Anfragen vor dem Speichern ab. Wenn Sie JSON zuerst parsen, können sich Leerzeichen oder Schlüsselreihenfolge ändern, und die Bytes stimmen nicht mehr mit der signierten Nachricht überein.

Wie sollten Sie einen Webhook speichern und bestätigen?

Persistieren Sie ein verifiziertes Ereignis und die zugehörige dauerhafte Arbeit, bevor Sie Erfolg zurückgeben. Fügen Sie das Ereignis mit dem Schlüssel webhook-id ein. Fügen Sie den Arbeitsauftrag für ein neues Ereignis ein. Committen Sie beides in einer Transaktion oder einem gleichwertigen dauerhaften Inbox-Outbox-Design.

read raw bytes and headers
verify the signature and timestamp with the Bird SDK
begin a durable transaction
  insert the inbox event keyed by webhook-id, unless it already exists
  insert a durable work item for a new event
commit the transaction
return 204
worker processes the persisted event idempotently

Ein Duplikat, das bereits dauerhaft gespeichert ist, kann 204 erhalten, ohne weitere Arbeit zu erzeugen. Geben Sie non-2xx zurück, wenn der dauerhafte Commit fehlschlägt, damit Bird die Zustellung erneut versucht. Sobald Sie Erfolg zurückgeben, starten Sie den lokalen Worker aus Ihrem dauerhaften Datensatz neu, anstatt zu erwarten, dass Bird das Ereignis erneut sendet.

Diese Reihenfolge ist ein Anwendungsdesign für die At-least-once-Zustellsemantik von Bird. Es ist keine Queue, die Bird für Sie betreibt. Die Anleitung zu Duplikaten und Idempotenz behandelt die Deduplizierungsentscheidung ausführlicher.

Wie funktionieren Webhook-Retries und Replay?

Bird gibt einer normalen Zustellung 15 Sekunden, um eine Antwort zu empfangen. Jeder 2xx-Status gilt als Erfolg. Ein non-2xx-Status, ein Redirect oder ein Timeout führt zum Fehlschlag und folgt dem Retry-Zeitplan.

Die Kurve umfasst 8 Versuche einschließlich der ersten Anfrage. Jede Verzögerung wird mit plus oder minus 20 % Jitter angewendet. Ein 429 oder Verbindungs-Timeout erhöht die Basisverzögerung auf 60 Sekunden. Ein positiver Retry-After-Wert wird zwischen dieser Basis und dem Doppelten der Basis vor Jitter eingegrenzt, sodass die Tabelle Basisverzögerungen und keine exakten Ankunftszeiten beschreibt. Unter Wie fehlgeschlagene Webhooks erneut versucht werden finden Sie den Fehlerpfad.

Zustellungen sind ungeordnet. Aktualisieren Sie den aktuellen Anwendungszustand daher nicht allein auf Basis der Ankunftsreihenfolge. Verwenden Sie den Ereignis-timestamp und Ihren Ressourcenzustand, wenn Ereignisse in falscher Reihenfolge eintreffen können.

Wenn eine Zustellung fehlt, prüfen Sie die Webhook-Versuche. Beheben Sie den Empfänger. Erstellen Sie ein Webhook-Replay. Bird überspringt Zustellungen, die der Endpunkt bereits erfolgreich empfangen hat. Ein Replay verwendet die originale webhook-id wieder, sodass derselbe Dedupe-Schlüssel schützt.

Was sollten Sie als Nächstes verbinden, nachdem Sie die Webhook-Grundlagen kennen?

Erstellen Sie einen Endpunkt. Verifizieren und dauerhaft annehmen Sie die signierten Zustellungen. Prüfen Sie die Zustellversuche. Spielen Sie verpasste Ereignisse erneut ab. Verwenden Sie dann die Secret-Rotation, um ein neues Signatur-Secret bereitzustellen, ohne Zustellungen zu verlieren.