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

Livraisons de webhook manquantes

Si vous ne recevez pas les livraisons webhook attendues, il est recommandé d’identifier le point où la livraison est manquante.

Déclenchez un événement qui devrait entraîner la livraison d’un webhook. Par exemple, si votre webhook est un webhook de référentiel abonné à l’événement issues, vous pouvez ouvrir un ticket sur ce référentiel.
Consultez 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 Affichage des livraisons de webhook.

Si le journal des livraisons récentes ne contient aucune livraison correspondant à l’événement webhook que vous avez déclenché à l’étape précédente, cela signifie que GitHub n’a pas tenté d’effectuer de livraison. Pour identifier la cause :
1. Patientez quelques minutes, puis vérifiez à nouveau. Les livraisons Webhook peuvent prendre quelques minutes avant d’apparaître.
2. Vérifiez que vous avez bien 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 d’avoir 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 bien abonné à l’événement que vous avez déclenché. Par exemple, si vous attendez la réception d’un webhook lorsque vous ouvrez un ticket, assurez-vous 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. Assurez-vous que votre webhook n’est pas affecté par les restrictions d’accès OAuth app. Si votre webhook a été créé par un OAuth app au nom d’un utilisateur qui a autorisé le OAuth app, le webhook sera automatiquement désactivé s’il s’agit d’un webhook d’organisation ou de référentiel pour une organisation dont l’accès est restreint par le OAuth app. Pour plus d’informations, consultez À propos des restrictions d’accès des applications OAuth dans la documentation GitHub Free.
6. Vérifiez si votre événement a atteint une limite documentée. Par exemple, si vous effectuez plus de trois pushs simultanément, 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 Événements et charges utiles du webhook.
7. Vérifiez l’état des webhooks à githubstatus.com.
Si le journal des livraisons récentes indique qu’une erreur s’est produite lors de la livraison, cela signifie que GitHub a tenté de livrer le colis, mais sans succès. Cela est généralement dû à un problème avec votre serveur. Consultez les sections ci-dessous pour résoudre l’erreur spécifique.
Consultez les journaux de votre serveur. Les informations contenues dans les journaux dépendent du code exécuté par votre serveur pour gérer les livraisons de webhooks. Afin de faciliter le diagnostic des problèmes sur votre serveur, il peut être utile d’ajouter des instructions de journalisation supplémentaires à votre code.

Il n’est pas possible d’avoir plus de 250 webhooks.

Vous pouvez créer jusqu’à 250 référentiels, organisations ou webhooks globaux pour chaque type d’événement. Si vous essayez d’en créer davantage, vous recevrez un message d’erreur indiquant que vous ne pouvez pas avoir plus de 250 webhooks.

Si vous avez besoin de plus de 250 webhooks, vous pouvez utiliser un proxy qui reçoit les webhooks de GitHub et les transfère vers un nombre illimité d’URL de destination.

L’hôte URL localhost n’est pas pris en charge

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

Pour transmettre des webhooks à votre serveur local à des fins de test, vous pouvez utiliser un service de transfert de webhooks. Pour plus d’informations, consultez Test de webhooks ou visitez https://smee.io/.

Échec de la connexion à l’hôte

L'erreur failed to connect to host se produit lorsque GitHub tente d'effectuer une livraison de webhook mais n'a pas pu résoudre l'URL du webhook en une adresse IP, ou lorsque des restrictions réseau empêchent la connexion à l'hôte.

Pour vérifier si un nom d’hôte correspond à une 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 indiquera que le serveur n’obtient pas de résultat pour le nom d’hôte.

Assurez-vous que votre serveur autorise les connexions provenant des adresses IP de GitHub. Vous pouvez utiliser le point de terminaison GET /meta pour trouver 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 procède occasionnellement à des modifications de ses adresses IP. Il est donc recommandé de mettre à jour régulièrement votre liste d’adresses IP autorisées.

Échec de la connexion au réseau

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

Délai dépassé

L’erreur timed out indique que GitHub n’a pas reçu de réponse de votre serveur dans les 30 secondes suivant l’envoi d’un webhook.

Votre serveur devrait répondre avec une réponse 2xx dans les 30 secondes suivant la réception d’une notification 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.

Afin de répondre en temps opportun, il peut être utile de configurer une file d’attente pour traiter les charges utiles des webhooks 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 webhooks. Par exemple, vous pouvez utiliser des services tels que Hookdeck ou des bibliothèques telles que Resque (Ruby), RQ (Python) ou RabbitMQ.

Le certificat pair ne peut pas être authentifié avec les certificats d’autorité de certification donnés

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 lors de l’établissement de la connexion.

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

Vous pouvez également utiliser openssl pour faciliter le diagnostic du problème. Pour ce faire, veuillez exécuter openssl s_client -connect HOST:PORT dans un terminal. 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 lorsque votre serveur renvoie un statut 4xx ou 5xx en réponse à une livraison de webhook provenant de GitHub.

Configurez votre serveur pour qu’il renvoie un statut 2xx. Si votre serveur renvoie un statut 4xx ou 5xx, GitHub enregistrera la livraison comme un échec.

Les livraisons Webhooks ne fonctionnent pas correctement

GitHub peut envoyer des webhooks dans un ordre différent de celui dans lequel les événements se sont produits. Si vous avez besoin de connaître le moment où l’événement s’est produit par rapport à un autre événement, veuillez utiliser les horodatages inclus dans la charge utile de livraison.

Les livraisons Webhook ne sont pas instantanées

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

Échec de la vérification de la signature

Utilisez un secret webhook et l’en-tête X-Hub-Signature-256 pour vérifier que la livraison du webhook provient bien de GitHub. Pour plus d’informations, consultez « Validation des livraisons de webhook ».

Dans cet article