Skip to main content
The REST API is now versioned. For more information, see "About API versioning."

REST API endpoints for global webhooks

Use the REST API to manage global webhooks for your enterprise.

About global webhooks

These endpoints are only available to authenticated site administrators Normal users will receive a 404 response. To learn how to configure global webhooks, see About global webhooks.

Global webhooks are automatically installed on your enterprise. You can use global webhooks to automatically monitor, respond to, or enforce rules for users, organizations, teams, and repositories on your enterprise.

Global webhooks can subscribe to the organization, user, repository, team, member, membership, fork, and ping event types.

These endpoints only support authentication using a personal access token (classic). For more information, see "Managing your personal access tokens."

List global webhooks

Fine-grained access tokens for "List global webhooks"

This endpoint does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.

Parameters for "List global webhooks"

Headers
Name, Type, Description
accept string

Setting to application/vnd.github+json is recommended.

Query parameters
Name, Type, Description
per_page integer

The number of results per page (max 100). For more information, see "Using pagination in the REST API."

Default: 30

page integer

The page number of the results to fetch. For more information, see "Using pagination in the REST API."

Default: 1

HTTP response status codes for "List global webhooks"

Status codeDescription
200

OK

Code samples for "List global webhooks"

Request example

get/admin/hooks
curl -L \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ http(s)://HOSTNAME/api/v3/admin/hooks

Response

Status: 200
[ { "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://HOSTNAME/admin/hooks/1", "ping_url": "https://HOSTNAME/admin/hooks/1/pings" } ]

Create a global webhook

Fine-grained access tokens for "Create a global webhook"

This endpoint does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.

Parameters for "Create a global webhook"

Headers
Name, Type, Description
accept string

Setting to application/vnd.github+json is recommended.

Body parameters
Name, Type, Description
name string Required

Must be passed as "web".

config object Required

Key/value pairs to provide settings for this webhook.

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.

events array of strings

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

HTTP response status codes for "Create a global webhook"

Status codeDescription
201

Created

Code samples for "Create a global webhook"

Request example

post/admin/hooks
curl -L \ -X POST \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ http(s)://HOSTNAME/api/v3/admin/hooks \ -d '{"name":"web","events":["organization","user"],"config":{"url":"https://example.com/webhook","content_type":"json","secret":"secret"}}'

Response

Status: 201
{ "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://HOSTNAME/admin/hooks/1", "ping_url": "https://HOSTNAME/admin/hooks/1/pings" }

Get a global webhook

Fine-grained access tokens for "Get a global webhook"

This endpoint does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.

Parameters for "Get a global webhook"

Headers
Name, Type, Description
accept string

Setting to application/vnd.github+json is recommended.

Path parameters
Name, Type, Description
hook_id integer Required

The unique identifier of the hook. You can find this value in the X-GitHub-Hook-ID header of a webhook delivery.

HTTP response status codes for "Get a global webhook"

Status codeDescription
200

OK

Code samples for "Get a global webhook"

Request example

get/admin/hooks/{hook_id}
curl -L \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ http(s)://HOSTNAME/api/v3/admin/hooks/HOOK_ID

Response

Status: 200
{ "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://HOSTNAME/admin/hooks/1", "ping_url": "https://HOSTNAME/admin/hooks/1/pings" }

Update a global webhook

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

Fine-grained access tokens for "Update a global webhook"

This endpoint does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.

Parameters for "Update a global webhook"

Headers
Name, Type, Description
accept string

Setting to application/vnd.github+json is recommended.

Path parameters
Name, Type, Description
hook_id integer Required

The unique identifier of the hook. You can find this value in the X-GitHub-Hook-ID header of a webhook delivery.

Body parameters
Name, Type, Description
config object

Key/value pairs to provide settings for this webhook.

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.

events array of strings

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

HTTP response status codes for "Update a global webhook"

Status codeDescription
200

OK

Code samples for "Update a global webhook"

Request example

patch/admin/hooks/{hook_id}
curl -L \ -X PATCH \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ http(s)://HOSTNAME/api/v3/admin/hooks/HOOK_ID \ -d '{"events":["organization"],"config":{"url":"https://example.com/webhook"}}'

Response

Status: 200
{ "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://HOSTNAME/admin/hooks/1", "ping_url": "https://HOSTNAME/admin/hooks/1/pings" }

Delete a global webhook

Fine-grained access tokens for "Delete a global webhook"

This endpoint does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.

Parameters for "Delete a global webhook"

Headers
Name, Type, Description
accept string

Setting to application/vnd.github+json is recommended.

Path parameters
Name, Type, Description
hook_id integer Required

The unique identifier of the hook. You can find this value in the X-GitHub-Hook-ID header of a webhook delivery.

HTTP response status codes for "Delete a global webhook"

Status codeDescription
204

No Content

Code samples for "Delete a global webhook"

Request example

delete/admin/hooks/{hook_id}
curl -L \ -X DELETE \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ http(s)://HOSTNAME/api/v3/admin/hooks/HOOK_ID

Response

Status: 204

Ping a global webhook

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

Fine-grained access tokens for "Ping a global webhook"

This endpoint does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.

Parameters for "Ping a global webhook"

Headers
Name, Type, Description
accept string

Setting to application/vnd.github+json is recommended.

Path parameters
Name, Type, Description
hook_id integer Required

The unique identifier of the hook. You can find this value in the X-GitHub-Hook-ID header of a webhook delivery.

HTTP response status codes for "Ping a global webhook"

Status codeDescription
204

No Content

Code samples for "Ping a global webhook"

Request example

post/admin/hooks/{hook_id}/pings
curl -L \ -X POST \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ http(s)://HOSTNAME/api/v3/admin/hooks/HOOK_ID/pings

Response

Status: 204