Get unlimited public & private packages + package-based permissions with npm Pro.Get started »


1.1.2 • Public • Published


A GitHub webhooks worker!

Build Status

githooked is a tiny library and companion CLI tool for handling GitHub webhooks hooks. This repo is a fork of and was created since the author of hookshot was innactive.

When setting up webhooks in your githooked dashboard, the types of events that should be sent to githooked should be set to: 'Just the push event'



var githooked = require('githooked');
githooked('refs/heads/master', 'git pull && make').listen(3000)

CLI Tool

githooked -r refs/heads/master 'git pull && make'


The library exposes a single function, githooked(). When called, this functions returns an express instance configured to handle webhooks pushes from GitHub. You can react to pushes to specific branches by listening to specific events on the returned instance, or by providing optional arguments to the githooked() function.

  .on('refs/heads/master', 'git pull && make')
githooked('refs/heads/master', 'git pull && make').listen(3000)


GitHooked supports up to three arguments: reference, action, and options. The first argument is the branch reference from the GitHooked webhook (i.e: refs/heads/master). If only one argument is supplied, it should be the action that needs to be ran. In this instance githooked will bind to every webhook event sent from GitHub.

githooked('branch/references', 'action', { /* options */});


References are specific webhook references or actions fired when editing tags or branches changes happen. This argument is provided so you can bind to specific branch or the following event hooks:


Actions can either be shell commands or JavaScript functions.

githooked('refs/heads/master', 'git pull && make').listen(3000)
githooked('refs/heads/master', function(info) {
  // do something with push info ...


Lastly, the third option is an object of configuration parameters. Usage:

githooked('push', 'git pull && make', {
  json: {
    limit: '100mb',
    strict: true
  middleware: [
    function(req, res, next) {
      // Do something

The following configuration options are:

json (Object)

These are arguments passed to express's body-parsers json() middleware

middleware (Function|Array[Function])

This is an array or function of valid express middleware. This middleware will be applied before any other express middleware. If an array is provided, the middleware will be applied in the order they are declared in the array.

secret (String)

GitHub webhooks can pass a secret which is used as an validation mechanism between your GitHub repo and your githooked server. Read more about it here. Validation of the payload will be the first operation performed on incoming requests. If using githooked for any serious purposes this option should be necessary. If validation failed an error event will be called with value of 'signature validation failed' or 'no provider signature':

  githooked.on('error', function(msg) {
    if ( msg === 'signature validation failed' ) {
      // do something

logFile (String|stream) TODO

If your action is a shell call, then this option will log all STDOUT and STDERR into the provided stream or file descriptor

Mounting to existing express servers

githooked can be mounted to a custom route on your existing express server:

// ...
app.use('/my-github-hook', githooked('refs/heads/master', 'git pull && make'));
// ...

Special Events

Special events are fired when branches/tags are created, deleted:

.on('create', function(info) {
  console.log('ref ' + info.ref + ' was created.')
.on('delete', function(info) {
  console.log('ref ' + info.ref + ' was deleted.')

The push event is fired when a push is made to any ref:

.on('push', function(info) {
  console.log('ref ' + info.ref + ' was pushed.')

Finally, the hook event is fired for every post-receive hook that is send by GitHub.

.on('push', function(info) {
  console.log('ref ' + info.ref + ' was pushed.')

Spawn Event

If githooked was created with a shell command as the action, it will throw a spawn event with the child_process spawn instance.

var server = githooked('refs/head/master', 'git pull && make').listen(3000);
server.on('spawn', function(spawn) {
  // Bind on close to get exit code
  spawn.on('close', function(code) {
    if ( code !== 0 ) {
      console.log('something went wrong');

CLI Tool

A companion CLI tool is provided for convenience. To use it, install githooked via npm using the -g flag:

npm install -g githooked

The CLI tool takes as argument a command to execute upon GitHub post-receive hook:

githooked 'echo "PUSHED!"'

You can optionally specify an HTTP port via the -p flag (defaults to 3000) and a ref via the -r flag (defaults to all refs):

githooked -r refs/heads/master -p 9001 'echo "pushed to master!"'


npm i githooked

DownloadsWeekly Downloads






Last publish


  • avatar