> ## Documentation Index
> Fetch the complete documentation index at: https://developer.jeko.africa/llms.txt
> Use this file to discover all available pages before exploring further.

# Comportement des Webhooks

> Comprendre le comportement des webhooks JEKO, les retries et la gestion des erreurs

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

## Duplication

Bien que JEKO s'efforce d'éviter les duplications, il est possible de recevoir le même webhook plusieurs fois (par exemple, lors des retries).

**Recommandation** : Implémentez une logique d'idempotence basée sur l'ID de l'événement ou la référence de la 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é