GitHub-webhooks: aanmaken, verifiëren en opnieuw versturen
GitHub-webhooks
GitHub-webhooks: instellen, events en signature controleren | We.Inc
Maak een GitHub-webhook, kies events, verifieer de X-Hub-Signature-256-header met werkende code en stuur mislukte leveringen opnieuw. Inclusief een signature-checker in de browser.
Een GitHub-webhook is een bericht dat GitHub naar de URL van uw server post zodra er iets gebeurt in een repository, zoals een push, een nieuwe issue of een release. U voegt hem toe onder Settings, Webhooks van de repository. Stel een secret in zodat u de X-Hub-Signature-256-header kunt controleren en valse leveringen kunt weigeren.
Feiten over GitHub-webhooks die u moet kennen (docs.github.com, oktober 2026)
Onderdeel
Wat GitHub documenteert
Signature-header
X-Hub-Signature-256, waarde begint met sha256=
Signature-methode
HMAC-hexdigest met SHA-256, met uw secret als sleutel
Responstijd
Meer dan 10 seconden wordt geregistreerd als mislukte levering
Automatische nieuwe pogingen
Geen; mislukte leveringen worden niet automatisch opnieuw verstuurd
Handmatig opnieuw versturen
Leveringen van de afgelopen 3 dagen
Maximale payloadgrootte
25 MB; grotere payloads worden niet afgeleverd
Met webhooks laat GitHub uw site of app weten wat er verandert op het moment dat het gebeurt, zodat u een site bij elke push opnieuw kunt bouwen, een bericht kunt plaatsen wanneer een issue wordt geopend of een changelog kunt bijwerken bij een release. Het belangrijke deel dat de meeste snelle handleidingen overslaan, is controleren of een levering echt van GitHub kwam. De checker hieronder berekent dezelfde signature die GitHub verstuurt, gewoon in uw browser.
Open de repository, klik op Settings, dan op Webhooks in de linkerzijbalk en daarna op Add webhook.
Typ uw endpoint onder Payload URL en kies application/json als content type, zodat de body als gewone JSON binnenkomt.
Vul onder Secret een lange willekeurige tekenreeks in en bewaar dezelfde waarde in de omgevingsvariabelen van uw server.
Kies bij de vraag welke events deze webhook moeten activeren alleen het push-event of selecteer losse events, vink Active aan en sla op.
GitHub stuurt meteen een ping-event; controleer het onder Recent Deliveries om te bevestigen dat uw server heeft geantwoord.
Antwoord snel. Geef binnen een ogenblik een 2xx-status terug en doe traag werk daarna in een achtergrondtaak, want een antwoord dat langer dan 10 seconden duurt, telt als mislukt.
Bereken de signature over de ruwe bytes van de body, vóór het parsen van JSON. Parsen en opnieuw serialiseren verandert de bytes, en dan faalt de controle.
Vergelijk signatures met een constant-time-functie zoals crypto.timingSafeEqual, nooit met een gewone ==-vergelijking.
Gebruik X-GitHub-Delivery, een unieke ID per levering, om dubbele leveringen over te slaan als u handmatig opnieuw verstuurt.
Abonneer u alleen op de events die u verwerkt. Minder events betekent minder verzoeken aan uw server en minder om te beveiligen.
Veelgestelde vragen
Probeert GitHub mislukte webhooks opnieuw?
Nee. De documentatie van GitHub zegt dat mislukte leveringen niet automatisch opnieuw worden verstuurd. U kunt er handmatig een opnieuw versturen vanuit Recent Deliveries, voor leveringen van de afgelopen 3 dagen.
Wat is de X-Hub-Signature-256-header?
Die wordt meegestuurd als de webhook een secret heeft. GitHub neemt de body van het verzoek, berekent een HMAC met SHA-256 met uw secret als sleutel, en stuurt het hexresultaat met sha256= ervoor. Uw server maakt dezelfde berekening en vergelijkt.
Welke events kan een webhook ontvangen?
Veel, waaronder push, pull_request, issues, release en workflow_run. De X-GitHub-Event-header noemt het event dat elke levering heeft veroorzaakt, en ping komt binnen wanneer u de hook voor het eerst aanmaakt.
Kan ik een webhook testen zonder publieke server?
Uw endpoint moet vanaf internet bereikbaar zijn, want GitHub post ernaartoe. Voor lokaal werk draait u een tunneltool die uw machine een tijdelijke publieke URL geeft, en gebruikt u die als Payload URL.
Webhook of de API pollen?
Een webhook stuurt elke wijziging naar u zodra die gebeurt; pollen betekent de API op een timer bevragen. Webhooks gebruiken minder verzoeken en komen sneller binnen, en dat telt, want API-aanroepen tellen mee voor de rate limits.
Wat er met elke levering binnenkomt
Elke levering is een POST met headers die haar beschrijven: X-GitHub-Event noemt het event, X-GitHub-Delivery is een unieke ID, X-GitHub-Hook-ID identificeert de webhook en de User-Agent begint altijd met GitHub-Hookshot/.
De body is de payload van het event. Bij een push staan daarin de commits en de branchreferentie, zodat een deployscript pushes naar andere branches dan de branch die het bouwt kan negeren.
Uw verificatiecode controleren met de testwaarden van GitHub
GitHub publiceert een bekende invoer zodat u kunt bewijzen dat uw code klopt voordat u live gaat: het secret It's a Secret to Everybody en de payload Hello, World! moeten een signature opleveren die begint met 757107ea.
De checker op deze pagina is met die waarden ingevuld. Als uw server er hetzelfde resultaat uit berekent, is uw verificatiecode correct.
Deze Express-route leest de ruwe body, berekent de HMAC met uw secret en vergelijkt die in constante tijd voordat de payload wordt vertrouwd.
express.raw bewaart precies de bytes die GitHub heeft ondertekend. Het secret komt uit een omgevingsvariabele, nooit uit de code.
Headers van een levering
Headers bij elke levering van een GitHub-webhook
Header
Wat erin staat
X-GitHub-Event
De naam van het event, zoals push of issues
X-GitHub-Delivery
Een unieke ID (GUID) voor deze levering
X-GitHub-Hook-ID
De ID van de webhook die hem verstuurde
X-Hub-Signature-256
sha256= plus de HMAC van de body, alleen als er een secret is ingesteld
User-Agent
Begint altijd met GitHub-Hookshot/
Webhook-signature-checker
Typ een secret en een ruwe request-body om de X-Hub-Signature-256-waarde te zien die GitHub zou versturen. Het draait in uw browser met de Web Crypto API; er wordt niets geüpload.
Webhook-secret
Ruwe request-body
Ontvangen signature-header (optioneel)
sha256=...
Berekende signature
Komt overeen: de signature van deze levering is geldig voor dat secret en die body.
Komt niet overeen: het secret, de bytes van de body of de header verschillen.
Testwaarden van GitHub laden
Met de testwaarden van GitHub moet het resultaat gelijk zijn aan: