koa-github-webhook-secure

Koa v2 middleware for processing GitHub Webhooks Securely

This library is a middleware for Koa v2 web servers that handles all the logic of receiving and verifying webhook requests from GitHub. It's based on the awesome work by @TinOo512, available here.

Example

import koa from 'koa';
import GithubWebhook from 'koa-github-webhook-secure';
 
const app = koa();
 
const githubWebhook = new GithubWebhook({
  path: '/webhook',
  secret: 'myhashsecret',
});
 
githubWebhook.on('push', ({ payload }) => {
  console.log('Received a push event for repo', payload.repository.name, '-', payload.ref);
});
 
app.use(githubWebhook.middleware());
 
app.listen(3000);

API

koa-github-webhook-secure exports a class, you must instantiate it with an options object. Your options object should contain:

• "path": the complete case sensitive path/route to match when looking at req.url for incoming requests. Any request not matching this path will yield to the "downstream" middleware.
• "secret": this is a hash key used for creating the SHA-1 HMAC signature of the JSON blob sent by GitHub. You should register the same secret key with GitHub. Any request not delivering a X-Hub-Signature that matches the signature generated using this key against the blob will throw an HTTP 400 error code.

The class inherits form EventEmitter. All Github events are emitted.

See the GitHub Webhooks documentation for more details on the events you can receive.

Additionally, there is a special '*' event you can listen to in order to receive everything.

License

koa-github-webhook-secure is licensed under the MIT License. See the included LICENSE.md file for more details.