Webhooks GitHub : configuration, événements et signature | We.Inc
Créez un webhook GitHub, choisissez les événements, vérifiez l'en-tête X-Hub-Signature-256 avec du code fonctionnel et renvoyez les livraisons échouées. Avec un vérificateur de signature dans le navigateur.
Un webhook GitHub est un message que GitHub envoie à l'URL de votre serveur chaque fois qu'il se passe quelque chose dans un dépôt, comme un push, une nouvelle issue ou une release. Vous l'ajoutez dans Settings, Webhooks du dépôt. Définissez un secret pour pouvoir vérifier l'en-tête X-Hub-Signature-256 et rejeter les fausses livraisons.
Ce qu'il faut savoir sur les webhooks GitHub (docs.github.com, octobre 2026)
Élément
Ce que documente GitHub
En-tête de signature
X-Hub-Signature-256, la valeur commence par sha256=
Méthode de signature
Condensé HMAC hexadécimal en SHA-256, avec votre secret comme clé
Temps de réponse
Au-delà de 10 secondes, la livraison est enregistrée comme échouée
Nouvelles tentatives automatiques
Aucune ; les livraisons échouées ne sont pas renvoyées automatiquement
Renvoi manuel
Livraisons des 3 derniers jours
Taille maximale du payload
25 MB ; les payloads plus lourds ne sont pas livrés
Les webhooks permettent à GitHub de prévenir votre site ou votre application d'un changement dès qu'il se produit : vous pouvez ainsi reconstruire un site à chaque push, publier un message à l'ouverture d'une issue ou mettre à jour un changelog à chaque release. Le point important que la plupart des guides rapides oublient, c'est de vérifier qu'une livraison vient bien de GitHub. Le vérificateur ci-dessous calcule la même signature que celle envoyée par GitHub, directement dans votre navigateur.
Ouvrez le dépôt, cliquez sur Settings, puis sur Webhooks dans la barre latérale gauche, puis sur Add webhook.
Saisissez votre endpoint dans Payload URL et choisissez application/json comme type de contenu pour que le corps arrive en JSON brut.
Saisissez une longue chaîne aléatoire dans Secret et gardez la même valeur dans les variables d'environnement de votre serveur.
Sous Which events would you like to trigger this webhook, choisissez uniquement l'événement push ou sélectionnez des événements individuels, cochez Active, puis enregistrez.
GitHub envoie immédiatement un événement ping ; vérifiez-le dans Recent Deliveries pour confirmer que votre serveur a répondu.
Répondez vite. Renvoyez un statut 2xx sans attendre et faites le travail lent ensuite dans une tâche en arrière-plan, car une réponse de plus de 10 secondes compte comme un échec.
Calculez la signature sur les octets bruts du corps, avant tout parsing JSON. Parser puis resérialiser modifie les octets et la vérification échoue.
Comparez les signatures avec une fonction à temps constant comme crypto.timingSafeEqual, jamais avec une simple comparaison ==.
Utilisez X-GitHub-Delivery, un identifiant unique par livraison, pour ignorer les doublons lorsque vous renvoyez à la main.
Abonnez-vous uniquement aux événements que vous traitez. Moins d'événements, c'est moins de requêtes vers votre serveur et moins de surface à sécuriser.
Questions fréquentes
GitHub relance-t-il les webhooks échoués ?
Non. La documentation de GitHub indique qu'il ne renvoie pas automatiquement les livraisons échouées. Vous pouvez en renvoyer une à la main depuis Recent Deliveries pour les livraisons des 3 derniers jours.
Qu'est-ce que l'en-tête X-Hub-Signature-256 ?
Il est envoyé lorsque le webhook possède un secret. GitHub prend le corps de la requête, calcule un HMAC en SHA-256 avec votre secret comme clé et envoie le résultat hexadécimal précédé de sha256=. Votre serveur refait le calcul et compare.
Quels événements un webhook peut-il recevoir ?
Beaucoup, notamment push, pull_request, issues, release et workflow_run. L'en-tête X-GitHub-Event indique l'événement qui a déclenché chaque livraison, et ping arrive à la création du hook.
Puis-je tester un webhook sans serveur public ?
Votre endpoint doit être accessible depuis internet, car GitHub y envoie ses requêtes. En local, utilisez un outil de tunnel qui donne à votre machine une URL publique temporaire, puis utilisez-la comme Payload URL.
Webhook ou interrogation de l'API ?
Un webhook vous envoie chaque changement au moment où il se produit ; le polling consiste à interroger l'API à intervalles réguliers. Les webhooks utilisent moins de requêtes et arrivent plus tôt, ce qui compte car les appels à l'API sont décomptés des limites de débit.
Ce qui arrive avec chaque livraison
Chaque livraison est un POST accompagné d'en-têtes qui la décrivent : X-GitHub-Event donne le nom de l'événement, X-GitHub-Delivery est un identifiant unique, X-GitHub-Hook-ID identifie le webhook, et le User-Agent commence toujours par GitHub-Hookshot/.
Le corps contient le payload de l'événement. Pour un push, il liste les commits et la référence de la branche, ce qui permet à un script de déploiement d'ignorer les pushs vers d'autres branches que celle qu'il construit.
Vérifier votre code avec les valeurs de test de GitHub
GitHub publie une entrée connue pour que vous puissiez prouver que votre code est correct avant la mise en production : le secret It's a Secret to Everybody et le payload Hello, World! doivent produire une signature qui commence par 757107ea.
Le vérificateur de cette page est prérempli avec ces valeurs. Si votre serveur obtient le même résultat à partir d'elles, votre code de vérification est correct.
Cette route Express lit le corps brut, calcule le HMAC avec votre secret et le compare en temps constant avant de faire confiance au payload.
express.raw conserve exactement les octets signés par GitHub. Le secret provient d'une variable d'environnement, jamais du code.
En-têtes de livraison
Les en-têtes de chaque livraison de webhook GitHub
En-tête
Ce qu'il contient
X-GitHub-Event
Le nom de l'événement, comme push ou issues
X-GitHub-Delivery
Un identifiant unique (GUID) pour cette livraison
X-GitHub-Hook-ID
L'identifiant du webhook qui l'a envoyée
X-Hub-Signature-256
sha256= suivi du HMAC du corps, uniquement si un secret est défini
User-Agent
Commence toujours par GitHub-Hookshot/
Vérificateur de signature de webhook
Saisissez un secret et un corps de requête brut pour voir la valeur X-Hub-Signature-256 que GitHub enverrait. Le calcul se fait dans votre navigateur avec la Web Crypto API ; rien n'est envoyé.
Secret du webhook
Corps brut de la requête
En-tête de signature reçu (facultatif)
sha256=...
Signature calculée
Correspondance : la signature de cette livraison est valide pour ce secret et ce corps.
Pas de correspondance : le secret, les octets du corps ou l'en-tête diffèrent.
Charger les valeurs de test de GitHub
Avec les valeurs de test de GitHub, le résultat doit être égal à :