Nouvelles tentatives et ordre

Votre endpoint tombera en panne un jour ou l'autre, et Wajub fera de nouvelles tentatives. C'est la partie facile. La partie difficile, c'est qu'une nouvelle tentative exécute votre handler une seconde fois sur un événement qu'il a peut-être déjà traité, et s'il expédie une commande à chaque exécution, il l'expédie deux fois.

Cette page couvre ce que Wajub garantit, ce qu'il ne garantit pas, et la forme de handler qui résiste aux deux.

Ce que Wajub garantit

Au moins une fois, pas exactement une fois. Chaque événement atteint votre endpoint au moins une fois. Certains l'atteindront plusieurs fois. Concevoir pour une livraison exactement une fois, c'est concevoir pour quelque chose qu'aucun système de webhooks ne fournit.

Aucune garantie d'ordre. Les événements sont livrés au fur et à mesure de leur production, via une file, avec des nouvelles tentatives intercalées. Un payment.succeeded peut arriver avant le payment.processing qui l'a précédé. Ne déduisez jamais l'état d'un paiement de l'ordre d'arrivée des événements. Lisez l'état dans le corps de l'événement, ou récupérez le paiement.

Quand une livraison compte comme un échec

Une livraison réussit quand votre endpoint répond avec n'importe quel 2xx en moins de 10 secondes. Toute autre issue est un échec.

Le calendrier des nouvelles tentatives

Cinq tentatives au total, puis la livraison est marquée comme échouée.

La séquence complète s'étend sur environ seize minutes. Après le cinquième échec, Wajub s'arrête. Votre endpoint n'est pas désactivé : le prochain événement sera quand même tenté, et vous pouvez rejouer à la main celui qui a échoué depuis Konsole ou avec POST /events/{id}/resend.

Dédupliquer : deux clés, deux significations

Chaque livraison porte les deux. Elles ne sont pas interchangeables, et choisir la mauvaise produit un bug que vous ne verrez pas avant d'ajouter un second endpoint.

id dans le corps, une valeur evt_…, identifie l'événement. Il est identique à chaque nouvelle tentative, et identique pour chaque endpoint qui reçoit cet événement.

X-Wajub-Delivery-Id dans les en-têtes, une valeur whd_…, identifie la livraison vers un endpoint. Il reste stable sur les cinq tentatives, et diffère pour chaque endpoint.

La forme du handler

Quatre étapes, dans cet ordre. Tout l'enjeu est dans l'ordre.

# The same event, arriving a second time after a timeout.
# Body id is identical, delivery id is not.
X-Wajub-Delivery-Id: whd_7Yh2MpL4tRb3nP8sZcXv
{"id":"evt_aio5DpN577tNU2vOxdmuZGhT","event":"payment.succeeded","data":{…}}

Marquez l'événement comme traité avant d'effectuer le travail, pas après. Si vous le marquez après, deux nouvelles tentatives arrivées à peu d'intervalle peuvent toutes deux passer la vérification et toutes deux s'exécuter.

Rapprocher l'événement de la requête qui l'a provoqué

Le corps contient la requête qui a produit l'événement :

request décrit l'enregistrement de l'événement, pas votre appel API. request.id vaut null, et request.idempotency_key est une valeur idem_… générée au moment où l'événement a été stocké. Aucun des deux ne vous renvoie l'en-tête Idempotency-Key que vous avez envoyé.

Associez plutôt un événement à une commande grâce à la ressource : data.reference est la reference que vous avez fournie à la création du paiement, et data.metadata est à votre disposition. Les deux survivent à chaque nouvelle tentative, car ils font partie de la ressource et non de la livraison.

api_version est la version courante de la plateforme au moment où l'événement a été enregistré, et le corps suit la forme de cette version. Fixer votre compte ou une requête sur une version plus ancienne change ce que renvoient vos appels API, jamais ce que reçoit votre endpoint.

Inspecter et rejouer

Chaque tentative est enregistrée avec son code de statut, son corps de réponse et sa latence dans Konsole. Une fois votre endpoint corrigé, vous pouvez rejouer une seule livraison, ou jusqu'à 100 livraisons échouées d'un coup, avec le payload d'origine et un en-tête fraîchement signé.