Repo Hooks API

The Repository Hooks API allows repository admins to manage the post-receive web and service hooks for a repository. There are two main APIs to manage these hooks: a JSON HTTP API, and PubSubHubbub.

Active hooks can be configured to trigger for one or more events. The default event is push. The available events are:

The payloads for all of the hooks mirror the payloads for the Event types, with the exception of the original push event.

A number of external services have already been integrated through the open source github-services project, including the generic Web Service service which can be used to define your own custom hooks. All possible names for hooks, the events they support, and their configuration can be seen at /hooks.

For a Hook to go through, the Hook needs to be configured to trigger for an event, and the Service has to listen to it. Most of the Services only listen for push events. However, the generic Web Service listens for all events. Other services like the IRC Service may only listen for push, issues, and pull_request events.

List

GET /repos/:owner/:repo/hooks

Response

Status: 200 OK
Link: <https://api.github.com/resource?page=2>; rel="next",
      <https://api.github.com/resource?page=5>; rel="last"
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
[
  {
    "url": "https://api.github.com/repos/octocat/Hello-World/hooks/1",
    "updated_at": "2011-09-06T20:39:23Z",
    "created_at": "2011-09-06T17:26:27Z",
    "name": "web",
    "events": [
      "push",
      "pull_request"
    ],
    "active": true,
    "config": {
      "url": "http://example.com",
      "content_type": "json"
    },
    "id": 1
  }
]

Get single hook

GET /repos/:owner/:repo/hooks/:id

Response

Status: 200 OK
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
{
  "url": "https://api.github.com/repos/octocat/Hello-World/hooks/1",
  "updated_at": "2011-09-06T20:39:23Z",
  "created_at": "2011-09-06T17:26:27Z",
  "name": "web",
  "events": [
    "push",
    "pull_request"
  ],
  "active": true,
  "config": {
    "url": "http://example.com",
    "content_type": "json"
  },
  "id": 1
}

Create a hook

POST /repos/:owner/:repo/hooks

Input

name
Required string - The name of the service that is being called. See /hooks for the possible names.
config
Required hash - A Hash containing key/value pairs to provide settings for this hook. These settings vary between the services and are defined in the github-services repo. Booleans are stored internally as “1” for true, and “0” for false. Any JSON true/false values will be converted automatically.
events
Optional array - Determines what events the hook is triggered for. Default: ["push"].
active
Optional boolean - Determines whether the hook is actually triggered on pushes.

Example: The “web” service hook takes these fields:

Here’s how you can setup a hook that posts raw JSON (instead of the default legacy format):

{
  "name": "web",
  "active": true,
  "events": [
    "push",
    "pull_request"
  ],
  "config": {
    "url": "http://example.com/webhook",
    "content_type": "json"
  }
}

Response

Status: 201 Created
Location: https://api.github.com/repos/user/repo/hooks/1
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
{
  "url": "https://api.github.com/repos/octocat/Hello-World/hooks/1",
  "updated_at": "2011-09-06T20:39:23Z",
  "created_at": "2011-09-06T17:26:27Z",
  "name": "web",
  "events": [
    "push",
    "pull_request"
  ],
  "active": true,
  "config": {
    "url": "http://example.com",
    "content_type": "json"
  },
  "id": 1
}

Edit a hook

PATCH /repos/:owner/:repo/hooks/:id

Input

config
Optional hash - A Hash containing key/value pairs to provide settings for this hook. Modifying this will replace the entire config object. These settings vary between the services and are defined in the github-services repo. Booleans are stored internally as “1” for true, and “0” for false. Any JSON true/false values will be converted automatically.
events
Optional array - Determines what events the hook is triggered for. This replaces the entire array of events. Default: ["push"].
add_events
Optional array - Determines a list of events to be added to the list of events that the Hook triggers for.
remove_events
Optional array - Determines a list of events to be removed from the list of events that the Hook triggers for.
active
Optional boolean - Determines whether the hook is actually triggered on pushes.

Example

{
  "active": true,
  "add_events": [
    "pull_request"
  ]
}

Response

Status: 200 OK
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
{
  "url": "https://api.github.com/repos/octocat/Hello-World/hooks/1",
  "updated_at": "2011-09-06T20:39:23Z",
  "created_at": "2011-09-06T17:26:27Z",
  "name": "web",
  "events": [
    "push",
    "pull_request"
  ],
  "active": true,
  "config": {
    "url": "http://example.com",
    "content_type": "json"
  },
  "id": 1
}

Test a push hook

This will trigger the hook with the latest push to the current repository if the hook is subscribed to push events. If the hook is not subscribed to push events, the server will respond with 204 but no test POST will be generated.

POST /repos/:owner/:repo/hooks/:id/tests

Note: Previously /repos/:owner/:repo/hooks/:id/test

Response

Status: 204 No Content
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

Delete a hook

DELETE /repos/:owner/:repo/hooks/:id

Response

Status: 204 No Content
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

PubSubHubbub

GitHub can also serve as a PubSubHubbub hub for all repositories. PSHB is a simple publish/subscribe protocol that lets servers register to receive updates when a topic is updated. The updates are sent with an HTTP POST request to a callback URL. Topic URLs for a GitHub repository’s pushes are in this format:

https://github.com/:owner/:repo/events/:event

The event can be any Event string that is listed at the top of this document.

The default format is what existing post-receive hooks should expect: A JSON body sent as the payload parameter in a POST. You can also specify to receive the raw JSON body with either an Accept header, or a .json extension.

Accept: application/json
https://github.com/:owner/:repo/events/push.json

Callback URLs can use either the http:// protocol, or github://. github:// callbacks specify a GitHub service.

# Send updates to postbin.org
http://postbin.org/123

# Send updates to Campfire
github://campfire?subdomain=github&room=Commits&token=abc123

The GitHub PubSubHubbub endpoint is: https://api.github.com/hub. (GitHub Enterprise users should use http://yourhost/api/v3/hub as the PubSubHubbub endpoint, but not change the hub.topic URI format.) A successful request with curl looks like:

curl -u "user" -i \
  https://api.github.com/hub \
  -F "hub.mode=subscribe" \
  -F "hub.topic=https://github.com/:owner/:repo/events/push" \
  -F "hub.callback=http://postbin.org/123"

PubSubHubbub requests can be sent multiple times. If the hook already exists, it will be modified according to the request.

Parameters

hub.mode
Required string - Either subscribe or unsubscribe.
hub.topic
Required string - The URI of the GitHub repository to subscribe to. The path must be in the format of /:owner/:repo/events/:event.
hub.callback
Required string - The URI to receive the updates to the topic.
hub.secret
Optional string - A shared secret key that generates a SHA1 HMAC of the outgoing body content. You can verify a push came from GitHub by comparing the raw request body with the contents of the X-Hub-Signature header. You can see our Ruby implementation, or the PubSubHubbub documentation for more details.