Global webhooks

Note: The Global Webhooks API is currently available for developers to preview. To access the API during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.superpro-preview+json

Warning: The API may change without advance notice during the preview period. Preview features are not supported for production use. If you experience any issues, contact your GitHub Enterprise site administrator.

Global webhooks are installed on a GitHub Enterprise instance. You can use global webhooks to automatically monitor, respond to, or enforce rules for users, organizations, teams, and repositories on your instance. Global webhooks can subscribe to the organization, user, repository, team, member, membership, fork and ping event types.

This API is only available to authenticated site administrators. Normal users will receive a 404 response if they try to access it. To learn how to configure global webhooks, see about global webhooks in the GitHub Help documentation.

List global hooks

Note: The Global Webhooks API is currently available for developers to preview. To access the API during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.superpro-preview+json

Warning: The API may change without advance notice during the preview period. Preview features are not supported for production use. If you experience any issues, contact your GitHub Enterprise site administrator.

GET /admin/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": "Global",
    "id": 1,
    "name": "web",
    "active": true,
    "events": [
      "organization",
      "user"
    ],
    "config": {
      "url": "https://example.com",
      "content_type": "json",
      "insecure_ssl": "0",
      "secret": "********"
    },
    "updated_at": "2017-12-07T00:14:59Z",
    "created_at": "2017-12-07T00:14:59Z",
    "url": "https://api.github.com/admin/hooks/1",
    "ping_url": "https://api.github.com/admin/hooks/1/pings"
  }
]

Get single global hook

Note: The Global Webhooks API is currently available for developers to preview. To access the API during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.superpro-preview+json

Warning: The API may change without advance notice during the preview period. Preview features are not supported for production use. If you experience any issues, contact your GitHub Enterprise site administrator.

GET /admin/hooks/:hook_id

Response

Status: 200 OK

{
  "type": "Global",
  "id": 1,
  "name": "web",
  "active": true,
  "events": [
    "organization",
    "user"
  ],
  "config": {
    "url": "https://example.com",
    "content_type": "json",
    "insecure_ssl": "0",
    "secret": "********"
  },
  "updated_at": "2017-12-07T00:14:59Z",
  "created_at": "2017-12-07T00:14:59Z",
  "url": "https://api.github.com/admin/hooks/1",
  "ping_url": "https://api.github.com/admin/hooks/1/pings"
}

Create a global hook

Note: The Global Webhooks API is currently available for developers to preview. To access the API during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.superpro-preview+json

Warning: The API may change without advance notice during the preview period. Preview features are not supported for production use. If you experience any issues, contact your GitHub Enterprise site administrator.

POST /admin/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 The events that trigger this webhook. A global webhook can be triggered by user and organization events. Default: user and organization.
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

{
  "name": "web",
  "events": [
    "organization",
    "user"
  ],
  "config": {
    "url": "https://example.com/webhook",
    "content_type": "json",
    "secret": "secret"
  }
}

Response

Status: 201 Created
Location: 

{
  "type": "Global",
  "id": 1,
  "name": "web",
  "active": true,
  "events": [
    "organization",
    "user"
  ],
  "config": {
    "url": "https://example.com",
    "content_type": "json",
    "insecure_ssl": "0",
    "secret": "********"
  },
  "updated_at": "2017-12-07T00:14:59Z",
  "created_at": "2017-12-07T00:14:59Z",
  "url": "https://api.github.com/admin/hooks/1",
  "ping_url": "https://api.github.com/admin/hooks/1/pings"
}

Edit a global hook

Note: The Global Webhooks API is currently available for developers to preview. To access the API during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.superpro-preview+json

Warning: The API may change without advance notice during the preview period. Preview features are not supported for production use. If you experience any issues, contact your GitHub Enterprise site administrator.

Parameters that are not provided will be overwritten with the default value or removed if no default exists.

PATCH /admin/hooks/:hook_id

Parameters

Name Type Description
config object Key/value pairs to provide settings for this webhook. These are defined below.
events array The events that trigger this webhook. A global webhook can be triggered by user and organization events. Default: user and organization.
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

{
  "name": "web",
  "events": [
    "organization"
  ],
  "config": {
    "url": "https://example.com/webhook"
  }
}

Response

Status: 200 OK

{
  "type": "Global",
  "id": 1,
  "name": "web",
  "active": true,
  "events": [
    "organization"
  ],
  "config": {
    "url": "https://example.com",
    "content_type": "form",
    "insecure_ssl": "0"
  },
  "updated_at": "2017-12-07T00:14:59Z",
  "created_at": "2017-12-07T00:14:59Z",
  "url": "https://api.github.com/admin/hooks/1",
  "ping_url": "https://api.github.com/admin/hooks/1/pings"
}

Ping a global hook

Note: The Global Webhooks API is currently available for developers to preview. To access the API during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.superpro-preview+json

Warning: The API may change without advance notice during the preview period. Preview features are not supported for production use. If you experience any issues, contact your GitHub Enterprise site administrator.

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

POST /admin/hooks/:hook_id/pings

Response

Status: 204 No Content

Delete a global hook

Note: The Global Webhooks API is currently available for developers to preview. To access the API during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.superpro-preview+json

Warning: The API may change without advance notice during the preview period. Preview features are not supported for production use. If you experience any issues, contact your GitHub Enterprise site administrator.

DELETE /admin/hooks/:hook_id

Response

Status: 204 No Content

Receiving Webhooks

In order for GitHub Enterprise 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 Enterprise will send along several HTTP headers to differentiate between event types and payload identifiers. See webhook headers for details.