Dépannage des webhooks

Voici les problèmes courants liés aux webhooks et comment les résoudre.

Échec de la vérification de signature

Non-utilisation du corps de payload brut

Problème : Lors de la génération de la signature, nous utilisons le corps sous forme de chaîne brute du payload du message. Si vous parsez le JSON puis le stringifiez à nouveau, la signature ne correspondra pas. Solution : Utilisez toujours le corps brut de la requête exactement tel qu’il a été reçu :

// WRONG - parsing and re-stringifying changes the format
const payload = JSON.parse(body);
verify(JSON.stringify(payload), headers); // Will fail!

// CORRECT - use the raw body
verify(rawBody, headers);

Mauvaise clé secrète

Problème : Utilisation du mauvais secret webhook ou décodage incorrect. Solution :

Assurez-vous d’utiliser le secret correct pour chaque endpoint (les secrets sont uniques par endpoint)
Supprimez le préfixe whsec_ avant le décodage base64

Horodatage expiré

Problème : L’horloge de votre serveur est désynchronisée, ce qui entraîne le rejet de webhooks pourtant valides. Solution : Assurez-vous que l’heure de votre serveur est synchronisée via NTP.

Webhooks non reçus

Endpoint inaccessible

Problème : Votre endpoint n’est pas accessible publiquement. Solution :

Assurez-vous que votre serveur est en cours d’exécution et que l’URL de l’endpoint est correcte
Vérifiez que les règles de pare-feu autorisent les requêtes HTTPS entrantes
Vérifiez que l’endpoint fonctionne avec un simple test curl

Problèmes SSL/TLS

Problème : Certificat SSL invalide ou expiré. Solution : Assurez-vous que votre endpoint dispose d’un certificat SSL valide émis par une autorité de certification (CA) de confiance.

Codes de réponse incorrects

Renvoyer des erreurs pour des traitements réussis

Problème : Vous renvoyez des codes de statut différents de 2xx même lorsque le webhook a été traité avec succès. Solution : Renvoyez toujours un code de statut 2xx lorsque vous avez bien reçu et mis en file d’attente le webhook pour traitement :

// CORRECT
app.post('/webhooks', (req, res) => {
  queue.add(req.body); // Add to queue for async processing
  res.status(200).send('OK'); // Acknowledge immediately
});

Timeouts

Le traitement prend trop de temps

Problème : Votre endpoint met plus de 15 secondes à répondre. Solution : Traitez les webhooks de manière asynchrone :

app.post('/webhooks', async (req, res) => {
  // Don't do this - blocks the response
  // await processOrder(req.body);
  
  // Do this instead - queue for background processing
  await queue.add('process-webhook', req.body);
  res.status(200).send('OK');
});

Récupération après échec

Réactiver un endpoint désactivé

Si votre endpoint a été désactivé après plusieurs échecs consécutifs :

Corrigez le problème sous-jacent
Allez dans Settings → Developers → Manage Webhooks dans le tableau de bord
Dans le portail webhook intégré, réactivez l’endpoint désactivé

Rejouer les messages échoués

Pour récupérer les webhooks manqués après une panne :

Accédez aux détails de votre endpoint
Cliquez sur Options > Recover Failed Messages
Sélectionnez la plage horaire à rejouer

Consultez les logs de webhook dans votre tableau de bord pour obtenir des messages d’erreur détaillés et les codes de réponse renvoyés par votre endpoint.

​Échec de la vérification de signature

​Non-utilisation du corps de payload brut

​Mauvaise clé secrète

​Horodatage expiré

​Webhooks non reçus

​Endpoint inaccessible

​Problèmes SSL/TLS

​Codes de réponse incorrects

​Renvoyer des erreurs pour des traitements réussis

​Timeouts

​Le traitement prend trop de temps

​Récupération après échec

​Réactiver un endpoint désactivé

​Rejouer les messages échoués

Échec de la vérification de signature

Non-utilisation du corps de payload brut

Mauvaise clé secrète

Horodatage expiré

Webhooks non reçus

Endpoint inaccessible

Problèmes SSL/TLS

Codes de réponse incorrects

Renvoyer des erreurs pour des traitements réussis

Timeouts

Le traitement prend trop de temps

Récupération après échec

Réactiver un endpoint désactivé

Rejouer les messages échoués