Meilleures pratiques en matière d’utilisation des webhooks

Abonnez-vous au nombre minimal d’événements

Abonnez-vous uniquement aux événements de webhook dont vous avez besoin. Cet abonnement réduit la quantité de travail nécessaire à votre serveur. Pour plus d’informations sur l’abonnement aux événements, consultez « Création de webhooks » et « Édition de webhooks ».

Utiliser un secret de webhook

Le secret Webhook doit être une chaîne de texte aléatoire avec une entropie élevée. Vous devez stocker en toute sécurité votre secret webhook de manière à ce que votre serveur puisse y accéder.

Utilisez la vérification HTTPS et SSL

Vous devez vous assurer que votre serveur utilise une connexion HTTPS. Par défaut, GitHub vérifie les certificats SSL pendant la livraison de webhooks. GitHub recommande de laisser la vérification SSL activée.

Autoriser les adresses IP de GitHub

Vous pouvez configurer une liste verte d’adresses IP pour votre serveur et ajouter les adresses IP que GitHub utilise pour les livraisons de webhook. Cette procédure peut bloquer les requêtes usurpées sur votre serveur.

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.

Pour plus d’informations, consultez « À propos des adresses IP de GitHub ».

Répondez dans 10 secondes

Votre serveur doit répondre avec une réponse 2XX dans 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 (Java).

Vérifier le type d’événement et l’action avant de traiter l’événement

Il existe plusieurs types d’événements webhook, et plusieurs événements peuvent comprendre plusieurs types d’actions. GitHub continue d’ajouter de nouveaux types d’événements et de nouvelles actions aux types d’événements existants. Votre application doit vérifier le type d’événement et l’action d’une charge utile webhook avant le traitement de la charge utile. Pour déterminer le type d’événement, vous pouvez utiliser l’en-tête de demande X-GitHub-Event. Pour déterminer le type d’action, vous pouvez utiliser la clé de premier niveau action dans la charge utile de l’événement.

Renouveler les livraisons manquées

Si votre serveur tombe en panne, vous devez renvoyer les webhooks manqués une fois que votre serveur est rétabli. Pour plus d’informations, consultez « Livrer de nouveau des webhooks ».

Utilisation de l’en-tête X-GitHub-Delivery

Dans une attaque par rejeu, un mauvais acteur intercepte une livraison de webhook et envoie de nouveau la livraison. Pour vous protéger contre les attaques par rejeu, vous pouvez utiliser l’en-tête X-GitHub-Delivery pour garantir que chaque livraison est unique pour chaque événement.

Pour aller plus loin

• Meilleures pratiques pour utiliser l'API REST
• Meilleures pratiques pour la création d’une application GitHub