Post-Receive Hooks

If you supply a post-receive URL, GitHub will POST to that URL when someone uses git push on that repository.

What we’ll send is JSON containing information about the push and the commits involved.

Here’s the template we use in Ruby to generate the JSON:

{ 
  :before     => before,
  :after      => after,
  :ref        => ref,
  :commits    => [{ 
    :message   => commit.message,
    :timestamp => commit.committed_date.xmlschema,
    :url       => commit_url,
    :author    => {
      :name  => commit.author.name,
      :email => commit.author.email
    }
  }],
  :repository => {
    :name  => repository.name,
    :url   => repo_url    
    :owner => {
      :name  => repository.owner.login,
      :email => repository.owner.email
    }
  }
}

This is sent as a POST with a single parameter: ‘payload’

So, for example, you’d do something like this in a Sinatra server:

post '/' do
  push = JSON.parse(params[:payload])
  "I got some JSON: #{push.inspect}" 
end

Send something to Campfire, IRC, Twitter, your CI server, whatever. It’s your data.

Here’s an example of a POST’d ‘payload’ JSON object:

{ 
  "before": "5aef35982fb2d34e9d9d4502f6ede1072793222d",
  "repository": {
    "url": "http://github.com/defunkt/github",
    "name": "github",
    "owner": {
      "email": "chris@ozmm.org",
      "name": "defunkt" 
    }
  },
  "commits": {
    "41a212ee83ca127e3c8cf465891ab7216a705f59": {
      "url": "http://github.com/defunkt/github/commit/41a212ee83ca127e3c8cf465891ab7216a705f59",
      "author": {
        "email": "chris@ozmm.org",
        "name": "Chris Wanstrath" 
      },
      "message": "okay i give in",
      "timestamp": "2008-02-15T14:57:17-08:00" 
    },
    "de8251ff97ee194a289832576287d6f8ad74e3d0": {
      "url": "http://github.com/defunkt/github/commit/de8251ff97ee194a289832576287d6f8ad74e3d0",
      "author": {
        "email": "chris@ozmm.org",
        "name": "Chris Wanstrath" 
      },
      "message": "update pricing a tad",
      "timestamp": "2008-02-15T14:36:34-08:00" 
    }
  },
  "after": "de8251ff97ee194a289832576287d6f8ad74e3d0",
  "ref": "refs/heads/master" 
}

For more information on this technique, see the Web Hooks Wiki.