Comment les webhooks échoués sont-ils réessayés, et les événements arrivent-ils dans l'ordre ?

Votre récepteur peut stocker un événement même si l'expéditeur ne reçoit jamais son accusé de réception. Un réessai peut donc répéter un traitement que votre application a déjà accepté.

Les réessais retardent certains événements. Des événements plus récents peuvent arriver avant la fin de ces réessais. Stockez les identifiants et les horodatages d'occurrence des événements pour que ces livraisons ne puissent pas écraser un traitement plus récent.

Qu'est-ce qui constitue une livraison échouée ?

Bird considère une livraison comme échouée lorsqu'il reçoit une réponse sans succès ou que la requête expire.

Renvoyez HTTP 2xx après avoir stocké l'événement pour arrêter les réessais de cette livraison. Une redirection, une erreur client ou une erreur serveur reste éligible au réessai.

Par exemple, 400 enregistre une requête rejetée mais ne demande pas à Bird de la supprimer. Utilisez une réponse d'erreur lorsque la vérification de signature ou le stockage durable échoue, afin que la livraison puisse être récupérée.

Stockez l'événement avant de l'accuser réception. Renvoyer un succès d'abord peut perdre l'événement si l'opération de stockage ultérieure échoue.

Placez le traitement lent dans un worker en arrière-plan pour que votre récepteur puisse répondre rapidement. Le rôle du récepteur est de vérifier et de conserver l'événement avant que ce traitement ne commence.

Quel est le calendrier des réessais ?

Bird applique sept délais de réessai après la tentative initiale, soit huit tentatives au total.

Le calendrier vous laisse environ 27,5 heures pour réparer un récepteur avant la fin des tentatives automatiques.

Bird ajuste aléatoirement chaque délai de plus ou moins 20 pour cent pour espacer les réessais après une panne. Un délai de cinq minutes varie donc de quatre à six minutes avant les autres ajustements.

Une réponse de limitation du débit ou un délai d'expiration peut modifier le prochain délai. Bird tient également compte de Retry-After, un en-tête de réponse demandant un délai avant la prochaine tentative. Considérez le calendrier comme une fenêtre de récupération plutôt qu'une échéance exacte.

Chaque réessai conserve le webhook-id de l'événement, ce qui permet à votre récepteur de reconnaître les doublons.

Que se passe-t-il après le dernier réessai ?

Les réessais automatiques s'arrêtent pour cette livraison. Vous pouvez demander le rejeu des livraisons qui ont échoué.

Vous demandez la redistribution avec createWebhookReplay, ou via la page du tableau de bord du endpoint. Le rejeu lit le journal des tentatives de livraison et sélectionne les événements qui y ont échoué. Un événement Bird jamais tenté, par exemple un événement arrivé pendant que le endpoint était en pause, n'a aucune tentative à sélectionner, le rejeu ne peut donc pas le récupérer.

La réponse est 202, ce qui signifie que le rejeu est mis en file d'attente pour une exécution en arrière-plan. Elle n'inclut ni un compteur ni un identifiant de tâche. Utilisez listWebhookAttempts pour inspecter les tentatives suivantes.

Chaque redistribution ne fait qu'une seule tentative au lieu de suivre le calendrier ci-dessus. Bird enregistre la tentative et termine le travail, que votre récepteur l'ait acceptée ou non. Rejouer vers un récepteur encore en panne ne coûte donc qu'une requête par événement au lieu de huit. Réparez le récepteur, puis relancez le replay. Ces échecs n'affectent pas la santé du endpoint. Une redistribution acceptée efface la dégradation.

Le rejeu ignore les livraisons déjà acquittées avec succès. Une redistribution conserve son webhook-id d'origine, votre gestion des doublons reste donc applicable.

Définissez since et until sous forme de chaînes date-heure pour délimiter la fenêtre de récupération. Les deux bornes sont inclusives. Elles sont comparées à l'heure de la tentative de livraison, pas à l'heure à laquelle l'événement s'est produit. Si vous omettez since, la fenêtre commence 24 heures avant la requête : une panne plus ancienne nécessite donc une heure de début explicite. Si vous omettez until, la fenêtre se termine à l'heure de la requête.

Les tentatives sont conservées pendant trois jours, ce qui correspond à la portée maximale du replay. Un since antérieur élargit la fenêtre sans récupérer quoi que ce soit de plus ancien. Un seul replay couvre au plus les 10 000 événements les plus anciens de la fenêtre ; une panne prolongée nécessite donc plusieurs fenêtres plus étroites.

Une organisation peut demander 20 rejeux par jour UTC. Toute demande supplémentaire reçoit 429 avec WebhookReplayQuotaExceeded, regroupez donc la récupération dans une fenêtre au lieu de demander un rejeu par événement.

Que se passe-t-il si mon endpoint échoue en permanence ?

Bird marque un endpoint défaillant comme dégradé. Il met la livraison en pause après environ cinq jours d'échecs ininterrompus.

Vous pouvez lire son status comme active, degraded ou paused. Un endpoint dégradé continue de recevoir des livraisons et des réessais. Une livraison réussie efface la dégradation et réinitialise le compteur d'échecs continus.

Un endpoint en pause cesse de recevoir des événements et ne reprend pas automatiquement. Réactivez-le avec updateWebhook, en définissant status à active. Rejouez ensuite la fenêtre, ce qui récupère les livraisons ayant échoué avant la pause. Réactivez d'abord : un rejeu demandé alors que le endpoint est encore en pause renvoie 202 et ne redistribue rien. Les valeurs de statut modifiables sont active et paused.

Modifier l'URL de réception url ou effectuer une livraison de test réussie efface également la dégradation. L'URL de remplacement doit être accessible publiquement HTTPS, les adresses privées ne peuvent donc pas rétablir la joignabilité. Les URL de plus de 2 048 caractères échouent à la validation, raccourcissez donc une URL générée avant de la soumettre.

Modifier la description du endpoint ou ses abonnements aux événements ne prouve pas qu'il peut recevoir des requêtes. Ces modifications laissent la dégradation en place, tout comme une livraison de test échouée.

Bird envoie un e-mail aux propriétaires de l'organisation lorsqu'un endpoint passe en dégradation. Aucun autre e-mail de dégradation n'est envoyé tant que le endpoint ne récupère pas. Les échecs répétés ne produisent donc pas un e-mail par tentative. Un échec après récupération déclenche une nouvelle période de dégradation.

Existe-t-il une file d'attente de lettres mortes ?

Bird ne fournit pas de file séparée d'événements échoués à consulter. Inspectez les tentatives de livraison et demandez un rejeu à la place.

Réparez le récepteur, réactivez-le si nécessaire et rejouez la fenêtre concernée. Il n'y a pas de file séparée à vider ensuite.

Les événements arrivent-ils dans l'ordre ?

Les événements peuvent arriver dans un ordre différent de celui dans lequel ils se sont produits.

Un événement email.delivered peut arriver avant l'événement email.accepted du même message. Comparez les heures des événements dans timestamp avant d'appliquer un changement qui écraserait un état plus récent.

Suivez chaque composante d'un coût SMS séparément. Par exemple, les frais de livraison et les frais opérateur sont des composantes de coût distinctes.

L'objet cost est null tant qu'une composante n'a pas été tarifée. Ses valeurs de composante sont des chaînes décimales ou null. Le champ amount est une chaîne décimale totalisant les composantes présentes dans ce payload.

Fusionnez chaque composante en utilisant l'horodatage d'événement le plus récent. Remplacer l'objet entier peut effacer une composante fournie par un autre événement ou restaurer un montant plus ancien.

Une composante null signifie qu'elle n'a pas été tarifée dans ce payload. Cela ne signifie pas un montant de zéro. Événements SMS décrit cette fusion en contexte, et webhooks couvre la sémantique de livraison.