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

​

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

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

• 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 (< 5 secondes)
• Traitement idempotent implémenté
• 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é