Comment fonctionnent les webhooks Resend ?

Le workflow des webhooks Resend

Le workflow commence lorsque vous créez un endpoint HTTPS public et l’enregistrez dans Resend avec les types d’événements dont votre application a besoin. Lorsqu’un événement correspondant se produit, Resend envoie une requête POST contenant un payload JSON. Ce payload comprend un type, comme email.sent, email.delivered, email.bounced ou email.complained, une date de création et des données propres à l’événement. Aiguillez le traitement selon le champ type, au lieu de supposer que tous les payloads ont la même forme.

Vérifiez la requête avant de la traiter

Lisez la requête sous forme de texte brut et vérifiez-la avec le secret de signature du webhook et les en-têtes svix-id, svix-timestamp et svix-signature. Faites-le avant d’analyser le payload ou d’agir en conséquence. Analyser le JSON puis le resérialiser peut modifier les octets et faire échouer une signature légitime. Rejetez les requêtes qui ne passent pas la vérification, et conservez le secret de signature dans un gestionnaire de secrets ou une variable d’environnement protégée plutôt que dans le code source.

Rendez le traitement des événements idempotent

Resend documente une livraison « au moins une fois » : le même événement peut donc atteindre votre endpoint plusieurs fois. Stockez le svix-id avec une contrainte d’unicité et ignorez la logique métier lorsque cet identifiant a déjà été traité. Ne vous fiez pas non plus à l’ordre d’arrivée, car les nouvelles tentatives et les délais réseau peuvent réordonner les événements. Utilisez la valeur created_at de l’événement lorsque l’ordre compte, et modélisez les changements de statut de sorte qu’un événement plus ancien ne puisse pas écraser accidentellement un état plus récent.

Accusez réception rapidement et traitez en toute sécurité

Renvoyez un HTTP 200 une fois l’événement vérifié et enregistré de façon durable, puis effectuez le travail plus lent via une file d’attente ou un worker en arrière-plan. Un timeout ou une réponse d’échec déclenche une nouvelle tentative de livraison : des handlers synchrones longs créent donc des doublons évitables. Séparez l’ingestion des effets de bord, comme la mise à jour d’une entrée de suppression, la notification du support ou l’enregistrement d’un bounce. Chaque effet de bord doit lui aussi pouvoir être répété sans risque, ou être protégé par l’identifiant d’événement stocké.

Testez les nouvelles tentatives, les rejeux et la reprise après incident

Testez l’endpoint avec des types d’événements représentatifs avant la mise en production, y compris des signatures invalides, des identifiants en double, des horodatages dans le désordre et des pannes temporaires de base de données. Resend retente les livraisons échouées selon un calendrier de backoff et vous permet de rejouer les messages de webhook échoués comme réussis. Utilisez le rejeu pour récupérer après une panne ou valider un handler mis à jour, mais gardez la déduplication active pour que la reprise ne répète pas les effets de bord visibles par les clients.

Les questions que posent les équipes

Sources primaires

• Gérer les webhooks — Resend
• Vérifier les requêtes de webhook — Resend
• Nouvelles tentatives et rejeux — Resend
• Types d’événements de webhook — Resend