Résolution des problèmes liés aux webhooks

Echec des livraisons de webhook

Si vous ne recevez pas les livraisons de webhook attendues, vous devez identifier le point d’échec de la livraison.

1. Déclenchez un événement que vous prévoyez de générer une livraison de webhook. Par exemple, si votre webhook constitue un référentiel de webhook abonné à l’événement issues, vous pouvez ouvrir un sujet dans ce référentiel.

2. Examinez le journal des livraisons récentes pour votre webhook. Pour plus d’informations sur la façon de procéder pour chaque type de webhook, consultez « AUTOTITRE ».

   Si le journal des livraisons récentes n’inclut pas une qui correspond à l’événement webhook que vous avez déclenché à l’étape précédente, alors GitHub n’a pas effectué de livaisons. Pour identifier la cause :

   1. Patientez quelques minutes, puis vérifiez à nouveau. Les livraisons de Webhook peuvent prendre quelques minutes avant de s'afficher.

   2. Assurez-vous que vous avez déclenché un événement à l’emplacement où votre webhook est configuré. Par exemple, si votre webhook est un webhook de référentiel, assurez-vous que vous avez déclenché l’événement dans le même référentiel que celui où votre webhook est configuré.

   3. Assurez-vous que votre webhook est abonné à l’événement que vous avez déclenché. Par exemple, si vous attendez une livraison de webhook quand vous ouvrez un sujet, vérifiez que votre webhook est abonné à l’événement issues.

   4. Assurez-vous que votre webhook est actif. Pour plus d’informations, consultez « Désactivation des webhooks ».

   5. Vérifiez que votre webhook n’est pas affecté par les restrictions d’accès OAuth app. Si votre webhook a été créé par une OAuth app au nom d’un utilisateur qui a autorisé OAuth app, le webhook est automatiquement désactivé s’il s’agit d’une organisation ou d’un webhook de référentiel pour une organisation disposant d’un accès restreint par les OAuth app. Pour plus d’informations, consultez « AUTOTITRE ».

   6. Vérifiez si votre événement peut avoir atteint une limite documentée. Par exemple, si vous envoyez plus de trois balises à la fois, l’événement push ne sera pas déclenché pour ce push. Pour plus d’informations sur les limites documentées pour chaque événement, consultez « AUTOTITRE ».

   7. Vérifiez l’état des webhooks à githubstatus.com.

   Si le journal des livraisons récentes indique qu’une erreur s’est produite durant la livraison, alors GitHub a tenté de livrer, mais elle a échoué. Cela est généralement dû à un problème avec votre serveur. Vous pouvez consulter les sections ci-dessous pour vous aider à résoudre l’erreur spécifique.

3. Examinez les journaux d’activité de votre serveur. Les informations contenues dans les journaux dépendent du code que votre serveur exécute pour gérer les livraisons de webhook. Pour vous aider à diagnostiquer les problèmes sur votre serveur, vous pouvez ajouter des instructions de journal supplémentaires à votre code.

Impossible d’obtenir plus de 20 webhooks

Vous pouvez créer jusqu’à 20 référentiel ou organisation webhooks pour chaque type d’événement. Si vous essayez de créer davantage, vous recevrez une erreur indiquant que vous ne pouvez pas avoir plus de 20 webhooks.

Si vous avez besoin de plus de 20 webhooks, vous pouvez exécuter un proxy qui reçoit des webhooks de GitHub et les transfère à un nombre illimité d’URL de destination.

Localhost hôte d’URL n’est pas pris en charge

Vous ne pouvez pas utiliser localhost ou 127.0.0.1 comme URL de webhook.

Pour fournir des webhooks à votre serveur local pour des tests, vous pouvez utiliser un service de transfert de webhook. Pour plus d’informations, consultez « Test de webhooks » ou visitez https://smee.io/.

Échec de la connexion à un hôte.

L’erreur failed to connect to host se produit quand GitHub tente une livraison de webhook, mais n’a pas pu résoudre l’URL du webhook en adresse IP.

Pour vérifier si un nom d’hôte est résolu en adresse IP, vous pouvez utiliser nslookup. Par exemple, si votre URL de charge utile est https://octodex.github.com/webhooks, vous pouvez exécuter nslookup octodex.github.com. Si le nom d’hôte n’a pas pu être résolu en adresse IP, la commande nslookup indique que le serveur ne trouve pas le nom d’hôte.

Échec de la connexion au réseau

L’erreur failed to connect to network indique que votre serveur a refusé la connexion quand GitHub a tenté de remettre un webhook.

Vous devez vous assurer que votre serveur autorise les connexions à partir des adresses IP de GitHub. Vous pouvez utiliser le point de terminaison GET /meta pour rechercher la liste actuelle des adresses IP de GitHub. Pour plus d’informations, consultez « Points de terminaison d’API REST pour les métadonnées ». GitHub apporte occasionnellement des modifications à ses adresses IP. Vous devez donc mettre à jour régulièrement votre liste verte d’adresses IP périodiquement.

Délai dépassé

L’erreur timed out indique que GitHub n’a pas reçu de réponse de votre serveur dans 10 secondes de livraison d’un webhook.

Votre serveur doit répondre avec une réponse 2xx dans les 10 secondes suivant la réception d’une livraison de webhook. Si votre serveur prend plus de temps qu’indiqué pour répondre, alors GitHub arrête la connexion et considère la livraison comme un échec.

Pour répondre en temps opportun, vous pouvez configurer une file d’attente pour traiter les charges utiles webhook de manière asynchrone. Votre serveur peut répondre lorsqu’il reçoit le webhook, puis traiter la charge utile en arrière-plan sans bloquer les futures livraisons de webhook. Par exemple, vous pouvez utiliser des services tels que Hookdeck ou des bibliothèques telles que Resque (Ruby), RQ (Python) ou RabbitMQ.

Le certificat de l'homologue ne peut pas être authentifié avec les certificats d'autorité de certification donnée.

Cette erreur indique qu’il existe un problème lié aux certificats de votre serveur. Les problèmes les plus courants sont les suivants :

• Votre serveur utilise un certificat auto-signé.
• Votre serveur n’envoie pas la chaîne de certificats complète quand la connexion est établie.

Pour diagnostiquer le problème, vous pouvez utiliser le test du serveur SSL à partir de SSL Labs. Ce service ne peut fonctionner qu’avec le port par défaut pour HTTPS (port 443) et ne peut fonctionner qu’avec des serveurs accessibles à partir d’Internet.

Vous pouvez également utiliser openssl pour diagnostiquer le problème. Pour ce faire, à partir d’un terminal, exécutez openssl s_client -connect HOST:PORT. Remplacez HOST par le nom d’hôte de votre serveur et PORT par le port. Par exemple : openssl s_client -connect example.com:443. Pour identifier les problèmes, recherchez verify error dans la sortie.

Réponse HTTP non valide

L’erreur invalid HTTP response se produit quand votre serveur retourne un état 4xx ou 5xx en réponse à une livraison de webhook à partir de GitHub.

Vous devez configurer votre serveur pour retourner un état 2xx. Si votre serveur retourne un état 4xx ou 5xx, GitHub enregistre la livraison comme un échec.

Les livraisons de webhooks sont hors commande

GitHub peut fournir des webhooks dans un ordre différent de celui dans lequel les événements ont eu lieu. Si vous devez savoir quand l’événement s’est produit par rapport à un autre, vous devez utiliser les horodateurs compris dans la charge utile de livraison.

Les livraisons de webhook ne sont pas immédiates

Les livraisons de Webhook peuvent prendre quelques minutes pour être livrées et apparaître dans le journal des livraisons récentes. Avant de conclure que votre livraison de webhook a échoué, attendez quelques minutes, puis vérifiez à nouveau.

Si votre compte connaît une forte augmentation des livraisons de webhooks, GitHub peut temporairement limiter le taux de livraison à votre compte. Si les livraisons de vos webhooks sont ralenties par GitHub, la propriété throttled_at pour chaque livraison concernée indique l’horodateur à laquelle la livraison a été limitée. Vous pouvez le vérifier à l’aide de l’API REST, consultez « Liste des livraisons pour un webhook de référentiel. »

Pour éviter les retards, abonnez-vous uniquement aux événements webhook nécessaires pour votre compte, en réduisant la fréquence des livraisons. Consultez « Meilleures pratiques en matière d’utilisation des webhooks. »

Échec de la vérification de la signature

Vous devriez utiliser un secret de webhook et l’en-tête X-Hub-Signature-256 pour vérifier qu’une livraison de webhook provient de GitHub. Pour plus d’informations, consultez « Validation des livraisons de webhook ».

Si vous êtes sûr que la charge utile provient de GitHub mais que la vérification de la signature échoue :

• Vérifiez que vous avez configuré un secret pour votre webhook. L’en-tête X-Hub-Signature-256 n’est pas présent si vous n’avez pas configuré de secret pour votre webhook. Pour plus d’informations sur la configuration d’un secret pour votre webhook, consultez « Édition de webhooks ».
• Vérifiez que vous utilisez le bon en-tête. GitHub recommande d’utiliser l’en-tête X-Hub-Signature-256, qui utilise l’algorithme HMAC-SHA256. L’en-tête X-Hub-Signature utilise l’algorithme HMAC-SHA1 et n’est inclus que pour des raisons d’héritage.
• Vérifiez que vous utilisez le bon algorithme. Si vous utilisez l’en-tête X-Hub-Signature-256, vous devez utiliser l’algorithme HMAC-SHA256.
• Vérifiez que vous utilisez le bon secret de webhook. Si vous ne connaissez pas la valeur du secret de votre webhook, vous pouvez mettre à jour le secret de votre webhook. Pour plus d’informations, consultez « Édition de webhooks ».
• Assurez-vous que la charge utile et les en-têtes ne sont pas modifiés avant la vérification. Par exemple, si vous utilisez un proxy ou un équilibreur de charge, assurez-vous que le proxy ou l’équilibreur de charge ne modifie pas la charge utile ou les en-têtes.
• Si votre implémentation de langage et de serveur spécifie un codage de caractères, vérifiez que vous traitez la charge utile en UTF-8. Les charges utiles des webhooks peuvent contenir des caractères Unicode.