Bonnes pratiques pour les Webhooks

​

Sécurité

​

Vérification de la signature

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

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 états intermédiaires : JEKO émet des webhooks pending avant l’état final
• Les retries : un webhook non acquitté est renvoyé (voir Comportement des webhooks)

​

Stratégies d’idempotence

1. État final : si la commande est déjà en success ou error de votre côté, ignorez le webhook
2. Référence de transaction : servez-vous de la référence pour retrouver la commande concernée
3. Base de données : stockez les identifiants de transaction déjà traités

​

Exemple : Vérification d’idempotence

async function processWebhook(payload) {
  // Les états intermédiaires ne décident de rien
  if (payload.status === 'pending') return;

  // La référence n'est pas à la racine : lire les deux emplacements possibles
  const reference =
    payload.transactionDetails?.reference ??
    payload.apiTransactionableDetails?.reference;

  const order = await db.findOrderByReference(reference);
  if (!order) return;

  // Déjà dans un état final : ne pas retraiter
  if (order.isFinalized) {
    console.log('Commande déjà finalisée, webhook ignoré:', reference);
    return;
  }

  await handleTransaction(order, payload);
}

​

Gestion d’erreurs

​

Codes de statut appropriés

• 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

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

​

Monitoring

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

​

Tests

​

Endpoint de test

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

​

Tests locaux

​

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 (timeout de 30 secondes)
• Référence lue avec fallback transactionDetails → apiTransactionableDetails
• Statut pending ignoré (jamais traité comme un échec)
• Traitement idempotent implémenté
• amount.amount converti avant comparaison (chaîne ou nombre)
• Gestion d’erreurs robuste
• Logging et monitoring configurés
• Tests effectués

​

Support

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