Skip to main content

​
Mécanisme de retry

JEKO utilise un système de retry automatique pour garantir la livraison des webhooks.

​
Politique de retry

  • Nombre de tentatives : Jusqu’à 3 tentatives en cas d’échec
  • Backoff exponentiel : Délai croissant entre chaque tentative
    • 1ère retry : ~1 minute après l’échec initial
    • 2ème retry : ~5 minutes après la 1ère retry
    • 3ème retry : ~15 minutes après la 2ème retry

​
Conditions de retry

Un webhook sera réessayé si :
  • Votre endpoint retourne un code HTTP >= 500 (erreur serveur)
  • Votre endpoint ne répond pas dans les 30 secondes (timeout)
  • Votre endpoint retourne un code HTTP 429 (trop de requêtes)

​
Conditions de succès

Un webhook est considéré comme livré avec succès si :
  • Votre endpoint retourne un code HTTP 200-299
  • La réponse est reçue dans les 30 secondes

​
Codes de statut HTTP

​
Codes de succès (pas de retry)

  • 200 OK : Webhook traité avec succès
  • 201 Created : Webhook traité avec succès
  • 202 Accepted : Webhook accepté pour traitement asynchrone

​
Codes d’erreur (retry)

  • 500 Internal Server Error : Erreur serveur - sera réessayé
  • 502 Bad Gateway : Erreur de gateway - sera réessayé
  • 503 Service Unavailable : Service indisponible - sera réessayé
  • 504 Gateway Timeout : Timeout - sera réessayé

​
Codes d’erreur client (pas de retry)

  • 400 Bad Request : Requête mal formée - ne sera pas réessayé
  • 401 Unauthorized : Non autorisé - ne sera pas réessayé
  • 404 Not Found : Endpoint introuvable - ne sera pas réessayé
  • 422 Unprocessable Entity : Données invalides - ne sera pas réessayé

​
Timeout

  • Timeout de connexion : 30 secondes
  • Timeout de réponse : 30 secondes
Si votre endpoint ne répond pas dans les 30 secondes, la requête sera considérée comme échouée et sera réessayée.

​
Ordre de livraison

Les webhooks peuvent être livrés dans un ordre différent de celui des événements. Ne supposez pas que les webhooks arrivent dans l’ordre chronologique. Recommandation : Utilisez le champ timestamp dans le payload pour déterminer l’ordre réel des événements.

​
Webhooks multiples et duplication

Vous recevrez plusieurs webhooks pour une même transaction, pour deux raisons distinctes :
  1. États intermédiaires : JEKO émet des webhooks au statut pending avant l’état final (success ou error). Ce n’est pas une duplication mais la progression normale de la transaction.
  2. Retries : un webhook non acquitté est renvoyé selon la politique ci-dessus.
Recommandation : Implémentez une logique d’idempotence basée sur la référence de la transaction, et ignorez tout webhook portant sur une commande déjà dans un état final. Voir Statuts de transaction.

​
Délai de livraison

Les webhooks sont généralement livrés dans les secondes qui suivent l’événement. Cependant, en cas de retry, il peut y avoir un délai plus long.

​
Monitoring

Pour surveiller la livraison de vos webhooks :
  1. Logs : Enregistrez tous les webhooks reçus avec leur timestamp
  2. Métriques : Surveillez les taux de succès/échec
  3. Alertes : Configurez des alertes pour les échecs répétés

​
Bonnes pratiques

  1. Réponse rapide : Traitez les webhooks rapidement et retournez une réponse immédiate
  2. Traitement asynchrone : Pour les traitements longs, acceptez le webhook immédiatement et traitez-le en arrière-plan
  3. Idempotence : Assurez-vous que le traitement d’un webhook est idempotent
  4. Gestion d’erreurs : Gérez les erreurs gracieusement et retournez toujours un code HTTP approprié