github-webhook-handler is a Node.js library providing a minimalist handler or middleware for processing GitHub Webhooks. It simplifies the process of receiving and verifying webhook requests, acting as an EventEmitter for various GitHub events such as `push` or `issues`. The current stable version is 2.1.1, released in April 2026, following a major v2.0.0 release in January 2026 that introduced ESM support, promises, and updated Node.js requirements (>=20). This package differentiates itself by focusing specifically on GitHub webhooks, handling SHA-1 HMAC signature verification and event parsing, allowing developers to quickly integrate webhook processing into their Node.js applications without dealing with low-level HTTP request body parsing and security checks. It features a straightforward API for creating a handler function that can be integrated into standard Node.js HTTP servers, designed for developers who need a robust, event-driven way to react to GitHub repository activity.
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Since v2.0.0, this package is ESM-only and exports `createHandler` as a default export. CommonJS `require` will not work.
import createHandler from 'github-webhook-handler'
Type import for configuring the handler options, useful for TypeScript projects.
import type { HandlerOptions } from 'github-webhook-handler'
Accesses the bundled JSON file containing GitHub event descriptions. Requires Node.js's JSON modules support (with { type: 'json' } assertion) for ESM.
import events from 'github-webhook-handler/events.json' with { type: 'json' }
This example demonstrates how to set up a basic Node.js HTTP server to listen for GitHub webhooks, create a handler, and respond to 'push' and 'issues' events, including error handling.
import http from 'node:http'
import createHandler from 'github-webhook-handler'
// Ensure these are secure in a production environment
const GITHUB_WEBHOOK_PATH = process.env.GITHUB_WEBHOOK_PATH ?? '/webhook'
const GITHUB_WEBHOOK_SECRET = process.env.GITHUB_WEBHOOK_SECRET ?? 'myhashsecret'
const LISTEN_PORT = parseInt(process.env.PORT ?? '7777', 10)
const handler = createHandler({
path: GITHUB_WEBHOOK_PATH,
secret: GITHUB_WEBHOOK_SECRET
})
http.createServer((req, res) => {
handler(req, res, (err) => {
res.statusCode = 404
res.end('no such location')
})
}).listen(LISTEN_PORT, () => {
console.log(`Server listening on port ${LISTEN_PORT} for GitHub webhooks at path ${GITHUB_WEBHOOK_PATH}`)
})
handler.on('error', (err) => {
console.error('Error handling webhook:', err.message)
})
handler.on('push', (event) => {
console.log('Received a push event for %s to %s',
event.payload.repository.name,
event.payload.ref)
// Add your logic here to react to a push event
})
handler.on('issues', (event) => {
console.log('Received an issue event for %s action=%s: #%d %s',
event.payload.repository.name,
event.payload.action,
event.payload.issue.number,
event.payload.issue.title)
// Add your logic here to react to an issue event
})
console.log('GitHub webhook handler initialized.')
Upgrade
Version history
Breaking-change detection hasn't run for this library yet.
Audit
Security & dependencies
CVE tracking and dependency tree are planned for a later release.