Webhooks

Organization webhooks allow you to receive HTTP POST payloads whenever certain events happen within the organization. Subscribing to these events makes it possible to build integrations that react to actions on GitHub.com. For more information on actions you can subscribe to, check out our Events documentation.

Scopes & Restrictions

All actions against organization webhooks require the authenticated user to be an admin of the organization being managed. Additionally, OAuth tokens require the admin:org_hook scope.

In order to protect sensitive data which may be present in webhook configurations, we also enforce the following access control rules:

  • OAuth applications cannot list, view, or edit webhooks which they did not create.
  • Users cannot list, view, or edit webhooks which were created by OAuth applications.

List hooks

GET /orgs/:org/hooks

Response

Status: 200 OK
Link: <https://api.github.com/resource?page=2>; rel="next",
      <https://api.github.com/resource?page=5>; rel="last"

[
  {
    "id": 1,
    "url": "https://api.github.com/orgs/octocat/hooks/1",
    "ping_url": "https://api.github.com/orgs/octocat/hooks/1/pings",
    "name": "web",
    "events": [
      "push",
      "pull_request"
    ],
    "active": true,
    "config": {
      "url": "http://example.com",
      "content_type": "json"
    },
    "updated_at": "2011-09-06T20:39:23Z",
    "created_at": "2011-09-06T17:26:27Z"
  }
]

Get single hook

GET /orgs/:org/hooks/:id

Response

Status: 200 OK

{
  "id": 1,
  "url": "https://api.github.com/orgs/octocat/hooks/1",
  "ping_url": "https://api.github.com/orgs/octocat/hooks/1/pings",
  "name": "web",
  "events": [
    "push",
    "pull_request"
  ],
  "active": true,
  "config": {
    "url": "http://example.com",
    "content_type": "json"
  },
  "updated_at": "2011-09-06T20:39:23Z",
  "created_at": "2011-09-06T17:26:27Z"
}

Create a hook

POST /orgs/:org/hooks

Parameters

Name Type Description
name string Required. Must be passed as "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 whether the hook is actually triggered on pushes.

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, payloads will be delivered with an X-Hub-Signature header. The value of this header is computed as the [HMAC hex digest of the body, using the secret as the key][hub-signature].
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": "http://example.com/webhook",
    "content_type": "json"
  }
}

Response

Status: 201 Created
Location: https://api.github.com/orgs/octocat/hooks/1

{
  "id": 1,
  "url": "https://api.github.com/orgs/octocat/hooks/1",
  "ping_url": "https://api.github.com/orgs/octocat/hooks/1/pings",
  "name": "web",
  "events": [
    "push",
    "pull_request"
  ],
  "active": true,
  "config": {
    "url": "http://example.com",
    "content_type": "json"
  },
  "updated_at": "2011-09-06T20:39:23Z",
  "created_at": "2011-09-06T17:26:27Z"
}

Edit a hook

PATCH /orgs/:org/hooks/:id

Parameters

Name Type Description
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 whether the hook is actually triggered on pushes.

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, payloads will be delivered with an X-Hub-Signature header. The value of this header is computed as the [HMAC hex digest of the body, using the secret as the key][hub-signature].
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,
  "events": [
    "pull_request"
  ]
}

Response

Status: 200 OK

{
  "id": 1,
  "url": "https://api.github.com/orgs/octocat/hooks/1",
  "ping_url": "https://api.github.com/orgs/octocat/hooks/1/pings",
  "name": "web",
  "events": [
    "pull_request"
  ],
  "active": true,
  "config": {
    "url": "http://example.com",
    "content_type": "json"
  },
  "updated_at": "2011-09-06T20:39:23Z",
  "created_at": "2011-09-06T17:26:27Z"
}

Ping a hook

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

POST /orgs/:org/hooks/:id/pings

Response

Status: 204 No Content

Delete a hook

DELETE /orgs/:org/hooks/: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.

For more best practices, see our guide.

Webhook Headers

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

Name Description
X-GitHub-Event The event type that was triggered.
X-GitHub-Delivery A guid to identify the payload and event being sent.
X-Hub-Signature The value of this header is computed as the HMAC hex digest of the body, using the secret config option as the key.