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

# Bonnes pratiques pour les Webhooks

> Recommandations pour une intégration robuste et sécurisée des webhooks JEKO

## Sécurité

### Vérification de la signature

**Toujours vérifier la signature** de chaque webhook avant de le traiter. Ne traitez jamais un webhook sans vérifier son authenticité.

```javascript theme={null}
// Exemple de vérification (voir samples pour implémentations complètes)
const signature = request.headers['jeko-signature'];
const expectedSignature = calculateHMAC(rawBody, webhookSecret);
if (signature !== expectedSignature) {
  return response.status(401).send('Invalid signature');
}
```

### HTTPS obligatoire

* Utilisez **uniquement HTTPS** pour vos endpoints webhook
* Ne configurez jamais une URL HTTP en production
* Utilisez des certificats SSL valides

### Secret webhook

* **Gardez votre secret webhook sécurisé** : Ne le commitez jamais dans votre code
* Utilisez des variables d'environnement pour stocker le secret
* Ne partagez jamais votre secret via des canaux non sécurisés
* Régénérez votre secret si vous suspectez une compromission

## Performance

### Réponse rapide

Répondez rapidement à votre endpoint webhook (dans les 5 secondes) pour éviter les retries :

1. **Acceptez immédiatement** : Retournez un code HTTP 200 dès la réception
2. **Traitement asynchrone** : Traitez le webhook en arrière-plan si nécessaire
3. **Queue** : Utilisez une queue pour les traitements longs

### Exemple : Traitement asynchrone

```javascript theme={null}
// Acceptez le webhook immédiatement
app.post('/webhook', async (req, res) => {
  // Vérifier la signature
  if (!verifySignature(req)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Retourner immédiatement
  res.status(200).send('OK');
  
  // Traiter en arrière-plan
  await processWebhookAsync(req.body);
});
```

## Idempotence

### Pourquoi l'idempotence est importante

Les webhooks peuvent être livrés plusieurs fois (lors des retries). Assurez-vous que le traitement d'un webhook est idempotent.

### Stratégies d'idempotence

1. **ID d'événement** : Utilisez l'ID de l'événement comme clé unique
2. **Référence de transaction** : Utilisez la référence de la transaction
3. **Base de données** : Stockez les événements traités dans une base de données

### Exemple : Vérification d'idempotence

```javascript theme={null}
async function processWebhook(webhookData) {
  const eventId = webhookData.data.id;
  
  // Vérifier si l'événement a déjà été traité
  const existingEvent = await db.findEvent(eventId);
  if (existingEvent) {
    console.log('Event already processed:', eventId);
    return; // Déjà traité, ignorer
  }
  
  // Traiter l'événement
  await handleEvent(webhookData);
  
  // Enregistrer l'événement comme traité
  await db.saveEvent(eventId, webhookData);
}
```

## Gestion d'erreurs

### Codes de statut appropriés

Retournez toujours un code HTTP approprié :

* **200-299** : Succès - webhook traité
* **400-499** : Erreur client - ne sera pas réessayé
* **500-599** : Erreur serveur - sera réessayé

### Gestion gracieuse des erreurs

1. **Logging** : Enregistrez toutes les erreurs pour le débogage
2. **Alertes** : Configurez des alertes pour les erreurs critiques
3. **Fallback** : Ayez un mécanisme de fallback si le webhook échoue

## Logging et monitoring

### Logs recommandés

Enregistrez les informations suivantes pour chaque webhook :

* Timestamp de réception
* Type d'événement
* ID de l'événement
* Statut de traitement (succès/échec)
* Temps de traitement

### Monitoring

Surveillez :

* Taux de succès/échec des webhooks
* Temps de réponse moyen
* Nombre de retries
* Erreurs récurrentes

## Tests

### Endpoint de test

Créez un endpoint de test pour valider votre intégration :

```javascript theme={null}
app.post('/webhook/test', (req, res) => {
  console.log('Test webhook received:', req.body);
  res.status(200).send('OK');
});
```

### Tests locaux

Utilisez des outils comme [ngrok](https://ngrok.com/) ou [localtunnel](https://localtunnel.github.io/www/) pour tester vos webhooks localement.

## Checklist d'intégration

* [ ] Endpoint HTTPS configuré
* [ ] Vérification de signature implémentée
* [ ] Secret webhook stocké de manière sécurisée
* [ ] Réponse rapide (\< 5 secondes)
* [ ] Traitement idempotent implémenté
* [ ] Gestion d'erreurs robuste
* [ ] Logging et monitoring configurés
* [ ] Tests effectués

## Support

Si vous rencontrez des problèmes avec vos webhooks, contactez le support JEKO à [hello@jeko.africa](mailto:hello@jeko.africa) avec :

* L'ID de l'événement
* Le timestamp de l'événement
* Les logs de votre endpoint
* Le code de statut retourné