Nouvelles tentatives et ordre

Quand votre endpoint échoue, Wajub livre l'événement à nouveau : votre handler peut donc s'exécuter deux fois sur le même événement. Cette page couvre ce que Wajub garantit et la forme de handler qui résiste à un doublon.

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.

Un cas rare fait plier cette promesse : les livraisons s'arrêtent tant que Wajub restreint vos webhooks, dans le cadre d'une restriction de votre compte ou de sa fermeture. Les événements sont toujours enregistrés et listés par GET /events, mais aucun n'est envoyé, ni à vos endpoints ni à wajub listen. Les événements enregistrés pendant la restriction ne sont pas envoyés quand elle est levée : lisez-les avec GET /events et rejouez ceux dont vous avez besoin avec POST /events/{id}/resend.

C'est pourquoi un rapprochement quotidien fait partie de toute intégration : ce n'est pas un filet de sécurité facultatif. Voir La page de retour n'est pas une confirmation.

Aucune garantie d'ordre. Les événements sont livrés au fur et à mesure de leur production, 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.

Combien de temps Wajub réessaie

Wajub continue d'essayer pendant 72 heures après la première tentative. Une fois les 72 heures écoulées, la livraison est marquée failed et 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. Si vous supprimez ou désactivez l'endpoint pendant qu'une livraison est encore retentée, les tentatives restantes sont abandonnées.

Dédupliquer sur l'id de l'événement

id dans le corps, une valeur evt_…, identifie l'événement. Il est identique à chaque nouvelle tentative, renvoi manuel compris, et identique pour chaque endpoint qui reçoit cet événement. Stockez-le, et ignorez un événement dont vous avez déjà traité l'id : expédier une commande, créditer un compte ou envoyer un reçu n'a alors lieu qu'une fois.

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.
# Its body id is the one of the first attempt.
{"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.

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é.

POST /events/{id}/resend envoie l'événement à chaque endpoint qui ne l'a pas encore accepté. Les relances ne sont pas décomptées de votre plan, mais un même événement repart vers le même endpoint au plus une fois toutes les 5 minutes, depuis Konsole ou depuis l'API. Un endpoint encore dans ce délai est ignoré et, quand tous le sont, l'appel répond 429 avec error_code: event_resend_cooldown et un en-tête Retry-After. Ce 429 n'est pas la limite de requêtes : renvoyer avant Retry-After obtient la même réponse.