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/:hook_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 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": "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/: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. 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

{
  "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/:hook_id/pings

Response

Status: 204 No Content

Delete a hook

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

For more best practices, see our guide.

Webhook headers

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