Anleitung · belegte Antwort

Wie funktionieren Resend-Webhooks?

Resend-Webhooks senden einen HTTPS-POST mit einem JSON-Event-Payload an Ihren registrierten Endpunkt, sobald ein Event zu einer E-Mail, einem Kontakt, einer Domain oder einer Sperrung eintritt. Ihr Endpunkt sollte die Signatur anhand des unveränderten Request-Bodys prüfen, das Event idempotent verarbeiten und zügig eine Erfolgsantwort zurückgeben.

Der Ablauf von Resend-Webhooks

Zunächst erstellen Sie einen öffentlichen HTTPS-Endpunkt und registrieren ihn in Resend mit den Event-Typen, die Ihre Anwendung benötigt. Tritt ein passendes Event ein, sendet Resend eine POST-Anfrage mit einem JSON-Payload. Der Payload enthält einen Typ wie email.sent, email.delivered, email.bounced oder email.complained, einen Erstellungszeitpunkt und eventspezifische Daten. Steuern Sie die Verarbeitung über das Feld type, statt davon auszugehen, dass jeder Payload gleich aufgebaut ist.

Anfrage vor der Verarbeitung prüfen

Lesen Sie die Anfrage als Rohtext ein und prüfen Sie sie mit dem Signing-Secret des Webhooks sowie den Headern svix-id, svix-timestamp und svix-signature. Tun Sie das, bevor Sie den Payload parsen oder darauf reagieren. Wird JSON geparst und anschließend erneut serialisiert, können sich die Bytes ändern, sodass eine legitime Signatur nicht mehr gültig ist. Weisen Sie Anfragen ab, die die Prüfung nicht bestehen, und bewahren Sie das Signing-Secret in einem Secret-Manager oder einer geschützten Umgebungsvariablen auf, nicht im Quellcode.

Events idempotent verarbeiten

Resend dokumentiert eine At-least-once-Zustellung. Dasselbe Event kann Ihren Endpunkt also mehrfach erreichen. Speichern Sie die svix-id mit einem Unique-Constraint und überspringen Sie die Geschäftslogik, wenn diese Kennung bereits verarbeitet wurde. Verlassen Sie sich auch nicht auf die Eingangsreihenfolge, denn Wiederholungsversuche und Netzwerkverzögerungen können Events vertauschen. Nutzen Sie den Wert created_at des Events, wenn die Reihenfolge wichtig ist, und modellieren Sie Statusänderungen so, dass ein älteres Event nicht versehentlich einen neueren Zustand überschreibt.

Schnell bestätigen, sicher verarbeiten

Geben Sie HTTP 200 zurück, sobald das Event geprüft und dauerhaft gespeichert ist, und erledigen Sie langsamere Arbeit über eine Warteschlange oder einen Hintergrund-Worker. Ein Timeout oder eine Antwort ohne Erfolgsstatus löst einen weiteren Zustellversuch aus. Lange synchrone Handler erzeugen daher vermeidbare Duplikate. Trennen Sie die Annahme von Seiteneffekten wie dem Aktualisieren eines Sperrlisteneintrags, dem Benachrichtigen des Supports oder dem Erfassen eines Bounces. Jeder Seiteneffekt sollte ebenfalls gefahrlos wiederholbar oder über die gespeicherte Event-Kennung abgesichert sein.

Wiederholungsversuche, Replays und Fehlerbehebung testen

Testen Sie den Endpunkt vor dem Produktivbetrieb mit repräsentativen Event-Typen, einschließlich ungültiger Signaturen, doppelter Kennungen, Zeitstempeln in falscher Reihenfolge und vorübergehender Datenbankausfälle. Resend wiederholt fehlgeschlagene Zustellungen nach einem Backoff-Zeitplan und ermöglicht Replays sowohl fehlgeschlagener als auch erfolgreicher Webhook-Nachrichten. Nutzen Sie Replays, um sich nach einem Ausfall zu erholen oder aktualisierten Handler-Code zu validieren. Lassen Sie die Deduplizierung dabei aktiv, damit die Wiederherstellung keine für Kunden sichtbaren Seiteneffekte wiederholt.

Häufige Fragen von Teams

Welche Antwort sollte ein Resend-Webhook-Endpunkt zurückgeben?

Geben Sie HTTP 200 zurück, nachdem die Anfrage geprüft und das Event dauerhaft angenommen wurde. Langsame Arbeit sollte asynchron weiterlaufen, damit der Provider nicht wegen eines Timeouts erneut zustellt.

Warum muss der unveränderte Request-Body erhalten bleiben?

Die Signatur bezieht sich auf die ursprünglichen Bytes der Anfrage. Wird JSON geparst und erneut serialisiert, können sich diese Bytes ändern. Die Prüfung schlägt dann fehl, obwohl die Anfrage legitim ist.

Kann ein Resend-Webhook-Event mehrfach zugestellt werden?

Ja. Resend dokumentiert eine At-least-once-Zustellung. Handler müssen Events deshalb deduplizieren, in der Regel, indem sie die eindeutige svix-id speichern, bevor sie geschäftliche Seiteneffekte ausführen.

Werden Resend-Webhook-Events in der richtigen Reihenfolge zugestellt?

Nein. Netzwerkverzögerungen und Wiederholungsversuche können die Eingangsreihenfolge verändern. Nutzen Sie Event-Zeitstempel und Regeln für Zustandsübergänge, wenn Ihre Anwendung eine verlässliche Abfolge rekonstruieren muss.

Wie stellt man fehlgeschlagene Resend-Webhook-Zustellungen wieder her?

Resend wiederholt fehlgeschlagene Zustellungen automatisch und unterstützt außerdem manuelle Replays. Beheben Sie zuerst das Problem am Endpunkt und spielen Sie dann die benötigten Events erneut ab. Lassen Sie die Idempotenzprüfungen dabei aktiviert.