express-github-webhook

1.0.6 verified Sat Apr 25 auth: no javascript maintenance

A lightweight Express middleware for handling GitHub Webhooks, version 1.0.6. It validates webhook signatures using a secret, parses event payloads, and emits events for easy integration. Unlike alternatives like `github-webhook-handler`, this package is designed specifically for Express and requires body-parser. Release cadence is low; last update was years ago, but the package is stable for basic use cases.

Common errors

error TypeError: GithubWebHook is not a constructor ↓

cause Using 'new' keyword on the factory function.

fix

Remove 'new': const webhookHandler = GithubWebHook({ secret: '...' });

error Error: secret is required to verify signature ↓

cause Request has a signature but no secret was provided in options.

fix

Provide a secret matching the GitHub webhook secret, or disable signature verification by not setting a secret (not recommended).

error Cannot find module 'body-parser' ↓

cause body-parser not installed.

fix

Run 'npm install body-parser' and ensure it is required before the middleware.

error webhookHandler.on('push', function(event, repo, data) {...}) but event is undefined ↓

cause Using incorrect callback signature for specific events.

fix

Use function(repo, data) for specific events, or function(event, repo, data) for '*' only.

error SyntaxError: Unexpected token u in JSON at position 0 ↓

cause body-parser not applied before the middleware, leaving req.body as undefined.

fix

Add app.use(bodyParser.json()) before app.use(webhookHandler).

Warnings

gotcha The package is CJS-only; it cannot be imported using ESM syntax (import). Use require() to avoid errors. ↓

fix Use require() instead of import.

gotcha GithubWebHook is a factory function, not a constructor. Calling new GithubWebHook() will throw an error. ↓

fix Call GithubWebHook(options) without new.

gotcha Event listeners for specific events (e.g., 'push') have a different callback signature from the wildcard '*' event. For specific events, the callback is (repo, data). For '*', it is (event, repo, data). ↓

fix Use the correct signature: webhookHandler.on('push', function(repo, data) { ... });

gotcha The package requires body-parser to be used before the middleware. If body-parser is not applied, the middleware will not parse the payload. ↓

fix Ensure app.use(bodyParser.json()) is called before app.use(webhookHandler).

deprecated body-parser is deprecated in favor of express's built-in express.json() since Express 4.16.0. The package still expects body-parser. ↓

fix Use express.json() instead of body-parser: app.use(express.json());

Install

npm install express-github-webhook

yarn add express-github-webhook

pnpm add express-github-webhook

Imports

GithubWebHook

wrong

import { GithubWebHook } from 'express-github-webhook';

correct

const GithubWebHook = require('express-github-webhook');

This package is CJS-only; no ESM support.

webhookHandler

wrong

const webhookHandler = new GithubWebHook();

correct

const webhookHandler = GithubWebHook({ secret: 'mysecret' });

GithubWebHook is a factory function, not a constructor. Do not use 'new'.

wrong

webhookHandler.on('push', function(event, repo, data) { ... });

correct

webhookHandler.on('push', function(repo, data) { ... });

For named events (not '*'), callback signature is (repo, data). The 'event' parameter is omitted.

Quickstart

Sets up an Express server with body-parser and the GitHub webhook middleware, listens for push events and wildcard events.

const express = require('express');
const bodyParser = require('body-parser');
const GithubWebHook = require('express-github-webhook');

const app = express();
app.use(bodyParser.json());

const webhookHandler = GithubWebHook({ path: '/webhook', secret: process.env.GITHUB_SECRET ?? '' });
app.use(webhookHandler);

webhookHandler.on('push', function(repo, data) {
  console.log('Push event on repo:', repo);
  console.log('Payload:', data);
});

webhookHandler.on('*', function(event, repo, data) {
  console.log(`Any event ${event} on repo ${repo}`);
});

app.listen(3000, () => console.log('Server listening on port 3000'));