GitScrum / Docs

Dépannage

Diagnostiquez et corrigez les problèmes courants des webhooks GitScrum : échecs de livraison, erreurs de timeout, problèmes de payload et erreurs de configuration.

Problèmes courants de webhook et comment les résoudre.

Le Webhook Ne Se Déclenche Pas

Endpoint non sauvegardé

Symptôme : Aucune requête n'arrive à votre serveur après avoir configuré un webhook.

Solution :

  1. Vérifiez que l'indicateur de statut est vert dans la configuration du webhook
  2. Réentrez l'URL et appuyez sur Entrée pour sauvegarder
  3. Actualisez la page et confirmez que l'URL persiste

Mauvais projet

Symptôme : Les webhooks fonctionnent pour un projet, mais pas pour un autre.

Solution : Les webhooks sont par projet. Vérifiez que vous avez configuré l'endpoint dans les paramètres du bon projet.

Plan Pro requis

Symptôme : La configuration du webhook apparaît, mais les endpoints ne s'activent pas.

Solution : Les webhooks nécessitent un plan Pro ou supérieur. Vérifiez l'état de facturation de votre workspace.

Échecs de Livraison

L'endpoint retourne un statut non-2xx

Symptôme : GitScrum affiche un échec de livraison pour un webhook.

Solution :

  • Vérifiez les logs de votre serveur pour les erreurs
  • Assurez-vous que votre endpoint retourne un code de statut 2xx (200, 201, 202, 204)
  • Vérifiez que le chemin de l'endpoint correspond exactement

Timeout de connexion

Symptôme : Les livraisons de webhook échouent constamment avec des erreurs de timeout.

Solution :

  • Retournez 200 immédiatement avant de traiter (utilisez le traitement en file d'attente)
  • Vérifiez que votre serveur répond dans les 30 secondes
  • Vérifiez que votre serveur n'est pas bloqué par un pare-feu

Erreurs SSL/TLS

Symptôme : Les livraisons de webhook HTTPS échouent.

Solution :

  • Assurez-vous que votre certificat SSL est valide et non expiré
  • Vérifiez que la chaîne de certificats est complète
  • Confirmez que votre serveur supporte TLS 1.2 ou supérieur

Problèmes de Payload

Payload vide ou malformé

Symptôme : Votre endpoint reçoit la requête, mais le corps est vide ou ne peut pas être parsé.

Solution :

  • Assurez-vous que votre serveur parse le content type application/json
  • Ajoutez le middleware express.json() (Node.js) ou équivalent
  • Vérifiez que votre bibliothèque de parsing supporte la taille du payload
// Express.js - ensure JSON parsing is enabled
app.use(express.json({ limit: '10mb' }));
# Flask - ensure JSON content type is handled
event = request.get_json(force=True)

Structure de payload inattendue

Symptôme : Votre code échoue car des champs attendus sont absents.

Solution :

  • Vérifiez toujours les valeurs null avant d'accéder aux propriétés imbriquées
  • Utilisez l'optional chaining en JavaScript : data?.workflow?.title
  • Validez la structure du payload avant le traitement
  • Consultez Format du Payload pour la référence complète des champs

Problèmes de Test

Le bouton de test envoie, mais le serveur ne reçoit pas

Symptôme : Cliquer sur le bouton de test affiche un succès, mais aucune requête n'arrive à votre serveur.

Solution :

  • Vérifiez que votre serveur est accessible publiquement (pas derrière un VPN ou un réseau local)
  • Confirmez que l'URL est correcte incluant le protocole (https://)
  • Essayez d'utiliser un outil d'inspection de requêtes comme webhook.site pour vérifier la livraison
  • Si vous utilisez ngrok, assurez-vous que le tunnel est toujours actif

Le test fonctionne, mais les événements réels ne se déclenchent pas

Symptôme : Les payloads de test arrivent, mais les événements réels ne déclenchent pas les webhooks.

Solution :

  • Vérifiez que l'événement spécifique est configuré (le test envoie à l'endpoint spécifique)
  • Confirmez que l'action que vous effectuez correspond au type d'événement
  • Assurez-vous que vous effectuez l'action dans le bon projet

Problèmes de Permissions

Impossible d'accéder aux paramètres des webhooks

Symptôme : L'onglet Webhooks n'est pas visible ou les paramètres sont en lecture seule.

Solution :

  • Seuls les rôles Manager et Owner peuvent configurer les webhooks
  • Contactez le gestionnaire du projet ou le propriétaire du workspace pour l'accès

Conseils de Débogage

Utilisez webhook.site pour l'inspection

Testez votre configuration de webhook en utilisant webhook.site :

  1. Allez sur webhook.site et copiez l'URL unique
  2. Collez-la comme endpoint dans les webhooks GitScrum
  3. Déclenchez un événement ou cliquez sur Test
  4. Inspectez les détails complets de la requête sur webhook.site

Vérifiez les logs de livraison

GitScrum enregistre chaque tentative de livraison de webhook incluant :

  • URL de l'endpoint
  • Corps du payload
  • Code de statut HTTP retourné
  • Horodatage

Examinez ces logs pour diagnostiquer les problèmes de livraison.

Développement local avec ngrok

Pour les tests locaux, utilisez ngrok pour créer un tunnel public :

ngrok http 3000

L'URL HTTPS fournie par ngrok peut être utilisée comme URL d'endpoint de webhook. Remplacez-la dans GitScrum lorsque l'URL du tunnel change.

Associé