Bonnes pratiques pour les Webhooks

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

// 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

Le délai d'attente est de 5 secondes. Accusez réception avant d'avoir fini votre traitement, sinon le webhook est réessayé :

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

// 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 de transaction : Utilisez le champ id du payload comme clé unique
2. Référence : Utilisez transactionDetails.reference si vous en avez fourni une à la création
3. Base de données : Stockez les transactions déjà traitées

Exemple : Vérification d'idempotence

async function processWebhook(transaction) {
  const transactionId = transaction.id;

  // Vérifier si la transaction a déjà été traitée
  const existing = await db.findTransaction(transactionId);
  if (existing) {
    console.log('Transaction already processed:', transactionId);
    return; // Déjà traitée, ignorer
  }

  await handleTransaction(transaction);

  // Enregistrer la transaction comme traitée
  await db.saveTransaction(transactionId, transaction);
}

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 :

• Date de réception
• id de la transaction
• transactionType et status
• Statut de votre 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 :

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 ou localtunnel 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 immédiate, traitement en arrière-plan
• Traitement idempotent implémenté
• Codes de statut corrects en cas d'erreur
• Logging et monitoring configurés
• Tests effectués

Support

Si vous rencontrez des problèmes avec vos webhooks, contactez le support Jèko à hello@jeko.africa avec :

• L'id de la transaction
• La valeur de executedAt
• Les logs de votre endpoint
• Le code de statut retourné