Webhooks

The Repository Webhooks API allows repository admins to manage the post-receive hooks for a repository. Webhooks can be managed using the JSON HTTP API, or the PubSubHubbub API.

If you would like to set up a single webhook to receive events from all of your organization's repositories, check out our API documentation for Organization Webhooks.

List hooks 

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"

[
  {
    "type": "Repository",
    "id": 12345678,
    "name": "web",
    "active": true,
    "events": [
      "push",
      "pull_request"
    ],
    "config": {
      "content_type": "json",
      "insecure_ssl": "0",
      "url": "https://example.com/webhook"
    },
    "updated_at": "2019-06-03T00:57:16Z",
    "created_at": "2019-06-03T00:57:16Z",
    "url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678",
    "test_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/test",
    "ping_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/pings",
    "last_response": {
      "code": null,
      "status": "unused",
      "message": null
    }
  }
]

Get single hook 

GET /repos/:owner/:repo/hooks/:hook_id

Response

Status: 200 OK

{
  "type": "Repository",
  "id": 12345678,
  "name": "web",
  "active": true,
  "events": [
    "push",
    "pull_request"
  ],
  "config": {
    "content_type": "json",
    "insecure_ssl": "0",
    "url": "https://example.com/webhook"
  },
  "updated_at": "2019-06-03T00:57:16Z",
  "created_at": "2019-06-03T00:57:16Z",
  "url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678",
  "test_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/test",
  "ping_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/pings",
  "last_response": {
    "code": null,
    "status": "unused",
    "message": null
  }
}

Create a hook

Repositories can have multiple webhooks installed. Each webhook should have a unique config. Multiple webhooks can share the same config as long as those webhooks do not have any events that overlap.

POST /repos/:owner/:repo/hooks

Parameters

Name Type Description
name string Use web to create a webhook. Default: web. This parameter only accepts the value web.
config object Required. Key/value pairs to provide settings for this webhook. These are defined below.
events array Determines what events the hook is triggered for. Default: ["push"]
active boolean Determines if notifications are sent when the webhook is triggered. Set to true to send notifications. Default: true.

The config object can accept the following keys:

Name Type Description
url string Required. The URL to which the payloads will be delivered.
content_type string The media type used to serialize the payloads. Supported values include json and form. The default is form.
secret string If provided, the secret will be used as the key to generate the HMAC hex digest value in the X-Hub-Signature header.
insecure_ssl string Determines whether the SSL certificate of the host for url will be verified when delivering payloads. Supported values include 0 (verification is performed) and 1 (verification is not performed). The default is 0. We strongly recommend not setting this to 1 as you are subject to man-in-the-middle and other attacks.

Example

Here's how you can create a hook that posts payloads in JSON format:

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

Response

Status: 201 Created
Location: https://api.github.com/repos/octocat/Hello-World/hooks/12345678

{
  "type": "Repository",
  "id": 12345678,
  "name": "web",
  "active": true,
  "events": [
    "push",
    "pull_request"
  ],
  "config": {
    "content_type": "json",
    "insecure_ssl": "0",
    "url": "https://example.com/webhook"
  },
  "updated_at": "2019-06-03T00:57:16Z",
  "created_at": "2019-06-03T00:57:16Z",
  "url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678",
  "test_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/test",
  "ping_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/pings",
  "last_response": {
    "code": null,
    "status": "unused",
    "message": null
  }
}

Edit a hook 

PATCH /repos/:owner/:repo/hooks/:hook_id

Parameters

Name Type Description
config object Key/value pairs to provide settings for this webhook. These are defined below.
events array Determines what events the hook is triggered for. This replaces the entire array of events. Default: ["push"]
add_events array Determines a list of events to be added to the list of events that the Hook triggers for.
remove_events array Determines a list of events to be removed from the list of events that the Hook triggers for.
active boolean Determines if notifications are sent when the webhook is triggered. Set to true to send notifications. Default: true.

The config object can accept the following keys:

Name Type Description
url string Required. The URL to which the payloads will be delivered.
content_type string The media type used to serialize the payloads. Supported values include json and form. The default is form.
secret string If provided, the secret will be used as the key to generate the HMAC hex digest value in the X-Hub-Signature header.
insecure_ssl string Determines whether the SSL certificate of the host for url will be verified when delivering payloads. Supported values include 0 (verification is performed) and 1 (verification is not performed). The default is 0. We strongly recommend not setting this to 1 as you are subject to man-in-the-middle and other attacks.

Example

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

Response

Status: 200 OK

{
  "type": "Repository",
  "id": 12345678,
  "name": "web",
  "active": true,
  "events": [
    "push",
    "pull_request"
  ],
  "config": {
    "content_type": "json",
    "insecure_ssl": "0",
    "url": "https://example.com/webhook"
  },
  "updated_at": "2019-06-03T00:57:16Z",
  "created_at": "2019-06-03T00:57:16Z",
  "url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678",
  "test_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/test",
  "ping_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/pings",
  "last_response": {
    "code": null,
    "status": "unused",
    "message": null
  }
}

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/:hook_id/tests

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

Response

Status: 204 No Content

Ping a hook

This will trigger a ping event to be sent to the hook.

POST /repos/:owner/:repo/hooks/:hook_id/pings

Response

Status: 204 No Content

Delete a hook 

DELETE /repos/:owner/:repo/hooks/:hook_id

Response

Status: 204 No Content

Receiving Webhooks

In order for GitHub to send webhook payloads, your server needs to be accessible from the Internet. We also highly suggest using SSL so that we can send encrypted payloads over HTTPS.

Webhook headers

GitHub will send along several HTTP headers to differentiate between event types and payload identifiers. See webhook headers for details.

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.

Response format

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

Callback URLs can use the http:// protocol. 

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

Subscribing

The GitHub PubSubHubbub endpoint is: https://api.github.com/hub. 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

Name Type Description
hub.mode string Required. Either subscribe or unsubscribe.
hub.topic string Required. The URI of the GitHub repository to subscribe to. The path must be in the format of /:owner/:repo/events/:event.
hub.callback string The URI to receive the updates to the topic.
hub.secret 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 the PubSubHubbub documentation for more details.