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

REST API endpoints for organization webhooks

Use the REST API to interact with webhooks in an organization.

About organization webhooks

Organization webhooks allow your server to receive HTTP POST payloads whenever certain events happen in an organization. For more information, see Webhooks documentation.

List organization webhooks

You must be an organization owner or have the "Manage organization webhooks" permission to use this endpoint.

OAuth app tokens and personal access tokens (classic) need admin:org_hook scope. OAuth apps cannot list, view, or edit webhooks that they did not create and users cannot list, view, or edit webhooks that were created by OAuth apps.

Fine-grained access tokens for "List organization webhooks"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

  • "Webhooks" organization permissions (read)

Parameters for "List organization webhooks"

Headers
Name, Type, Description
accept string

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

Path parameters
Name, Type, Description
org string Required

The organization name. The name is not case sensitive.

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 organization webhooks"

Status codeDescription
200

OK

404

Resource not found

Code samples for "List organization webhooks"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

get/orgs/{org}/hooks
curl -L \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/orgs/ORG/hooks

Response

Status: 200
[ { "id": 1, "url": "https://api.github.com/orgs/octocat/hooks/1", "ping_url": "https://api.github.com/orgs/octocat/hooks/1/pings", "deliveries_url": "https://api.github.com/orgs/octocat/hooks/1/deliveries", "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", "type": "Organization" } ]

Create an organization webhook

You must be an organization owner or have the "Manage organization webhooks" permission to use this endpoint.

OAuth app tokens and personal access tokens (classic) need admin:org_hook scope. OAuth apps cannot list, view, or edit webhooks that they did not create and users cannot list, view, or edit webhooks that were created by OAuth apps.

Fine-grained access tokens for "Create an organization webhook"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

  • "Webhooks" organization permissions (write)

Parameters for "Create an organization webhook"

Headers
Name, Type, Description
accept string

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

Path parameters
Name, Type, Description
org string Required

The organization name. The name is not case sensitive.

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 for delivery signature headers.

insecure_ssl string or number

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.

username string
password string
events array of strings

Determines what events the hook is triggered for. Set to ["*"] to receive all possible events.

Default: ["push"]

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 an organization webhook"

Status codeDescription
201

Created

404

Resource not found

422

Validation failed, or the endpoint has been spammed.

Code samples for "Create an organization webhook"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

post/orgs/{org}/hooks
curl -L \ -X POST \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/orgs/ORG/hooks \ -d '{"name":"web","active":true,"events":["push","pull_request"],"config":{"url":"http://example.com/webhook","content_type":"json"}}'

Response

Status: 201
{ "id": 1, "url": "https://api.github.com/orgs/octocat/hooks/1", "ping_url": "https://api.github.com/orgs/octocat/hooks/1/pings", "deliveries_url": "https://api.github.com/orgs/octocat/hooks/1/deliveries", "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", "type": "Organization" }

Get an organization webhook

You must be an organization owner or have the "Manage organization webhooks" permission to use this endpoint.

OAuth app tokens and personal access tokens (classic) need admin:org_hook scope. OAuth apps cannot list, view, or edit webhooks that they did not create and users cannot list, view, or edit webhooks that were created by OAuth apps.

Fine-grained access tokens for "Get an organization webhook"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

  • "Webhooks" organization permissions (read)

Parameters for "Get an organization webhook"

Headers
Name, Type, Description
accept string

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

Path parameters
Name, Type, Description
org string Required

The organization name. The name is not case sensitive.

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 an organization webhook"

Status codeDescription
200

OK

404

Resource not found

Code samples for "Get an organization webhook"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

get/orgs/{org}/hooks/{hook_id}
curl -L \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/orgs/ORG/hooks/HOOK_ID

Response

Status: 200
{ "id": 1, "url": "https://api.github.com/orgs/octocat/hooks/1", "ping_url": "https://api.github.com/orgs/octocat/hooks/1/pings", "deliveries_url": "https://api.github.com/orgs/octocat/hooks/1/deliveries", "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", "type": "Organization" }

Update an organization webhook

You must be an organization owner or have the "Manage organization webhooks" permission to use this endpoint.

OAuth app tokens and personal access tokens (classic) need admin:org_hook scope. OAuth apps cannot list, view, or edit webhooks that they did not create and users cannot list, view, or edit webhooks that were created by OAuth apps.

Fine-grained access tokens for "Update an organization webhook"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

  • "Webhooks" organization permissions (write)

Parameters for "Update an organization webhook"

Headers
Name, Type, Description
accept string

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

Path parameters
Name, Type, Description
org string Required

The organization name. The name is not case sensitive.

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 for delivery signature headers.

insecure_ssl string or number

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

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

name string

HTTP response status codes for "Update an organization webhook"

Status codeDescription
200

OK

404

Resource not found

422

Validation failed, or the endpoint has been spammed.

Code samples for "Update an organization webhook"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

patch/orgs/{org}/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" \ https://api.github.com/orgs/ORG/hooks/HOOK_ID \ -d '{"active":true,"events":["pull_request"]}'

Response

Status: 200
{ "id": 1, "url": "https://api.github.com/orgs/octocat/hooks/1", "ping_url": "https://api.github.com/orgs/octocat/hooks/1/pings", "deliveries_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/deliveries", "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", "type": "Organization" }

Delete an organization webhook

You must be an organization owner or have the "Manage organization webhooks" permission to use this endpoint.

OAuth app tokens and personal access tokens (classic) need admin:org_hook scope. OAuth apps cannot list, view, or edit webhooks that they did not create and users cannot list, view, or edit webhooks that were created by OAuth apps.

Fine-grained access tokens for "Delete an organization webhook"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

  • "Webhooks" organization permissions (write)

Parameters for "Delete an organization webhook"

Headers
Name, Type, Description
accept string

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

Path parameters
Name, Type, Description
org string Required

The organization name. The name is not case sensitive.

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 an organization webhook"

Status codeDescription
204

No Content

404

Resource not found

Code samples for "Delete an organization webhook"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

delete/orgs/{org}/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" \ https://api.github.com/orgs/ORG/hooks/HOOK_ID

Response

Status: 204

Get a webhook configuration for an organization

You must be an organization owner or have the "Manage organization webhooks" permission to use this endpoint.

OAuth app tokens and personal access tokens (classic) need admin:org_hook scope. OAuth apps cannot list, view, or edit webhooks that they did not create and users cannot list, view, or edit webhooks that were created by OAuth apps.

Fine-grained access tokens for "Get a webhook configuration for an organization"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

  • "Webhooks" organization permissions (read)

Parameters for "Get a webhook configuration for an organization"

Headers
Name, Type, Description
accept string

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

Path parameters
Name, Type, Description
org string Required

The organization name. The name is not case sensitive.

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 webhook configuration for an organization"

Status codeDescription
200

OK

Code samples for "Get a webhook configuration for an organization"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

get/orgs/{org}/hooks/{hook_id}/config
curl -L \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/orgs/ORG/hooks/HOOK_ID/config

Response

Status: 200
{ "content_type": "json", "insecure_ssl": "0", "secret": "********", "url": "https://example.com/webhook" }

Update a webhook configuration for an organization

You must be an organization owner or have the "Manage organization webhooks" permission to use this endpoint.

OAuth app tokens and personal access tokens (classic) need admin:org_hook scope. OAuth apps cannot list, view, or edit webhooks that they did not create and users cannot list, view, or edit webhooks that were created by OAuth apps.

Fine-grained access tokens for "Update a webhook configuration for an organization"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

  • "Webhooks" organization permissions (write)

Parameters for "Update a webhook configuration for an organization"

Headers
Name, Type, Description
accept string

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

Path parameters
Name, Type, Description
org string Required

The organization name. The name is not case sensitive.

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
url string

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 for delivery signature headers.

insecure_ssl string or number

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.

HTTP response status codes for "Update a webhook configuration for an organization"

Status codeDescription
200

OK

Code samples for "Update a webhook configuration for an organization"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

patch/orgs/{org}/hooks/{hook_id}/config
curl -L \ -X PATCH \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/orgs/ORG/hooks/HOOK_ID/config \ -d '{"url":"http://example.com/webhook","content_type":"json","insecure_ssl":"0","secret":"********"}'

Response

Status: 200
{ "content_type": "json", "insecure_ssl": "0", "secret": "********", "url": "https://example.com/webhook" }

List deliveries for an organization webhook

You must be an organization owner or have the "Manage organization webhooks" permission to use this endpoint.

OAuth app tokens and personal access tokens (classic) need admin:org_hook scope. OAuth apps cannot list, view, or edit webhooks that they did not create and users cannot list, view, or edit webhooks that were created by OAuth apps.

Fine-grained access tokens for "List deliveries for an organization webhook"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

  • "Webhooks" organization permissions (read)

Parameters for "List deliveries for an organization webhook"

Headers
Name, Type, Description
accept string

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

Path parameters
Name, Type, Description
org string Required

The organization name. The name is not case sensitive.

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.

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

cursor string

Used for pagination: the starting delivery from which the page of deliveries is fetched. Refer to the link header for the next and previous page cursors.

HTTP response status codes for "List deliveries for an organization webhook"

Status codeDescription
200

OK

400

Bad Request

422

Validation failed, or the endpoint has been spammed.

Code samples for "List deliveries for an organization webhook"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

get/orgs/{org}/hooks/{hook_id}/deliveries
curl -L \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/orgs/ORG/hooks/HOOK_ID/deliveries

Response

Status: 200
[ { "id": 12345678, "guid": "0b989ba4-242f-11e5-81e1-c7b6966d2516", "delivered_at": "2019-06-03T00:57:16Z", "redelivery": false, "duration": 0.27, "status": "OK", "status_code": 200, "event": "issues", "action": "opened", "installation_id": 123, "repository_id": 456, "throttled_at": "2019-06-03T00:57:16Z" }, { "id": 123456789, "guid": "0b989ba4-242f-11e5-81e1-c7b6966d2516", "delivered_at": "2019-06-04T00:57:16Z", "redelivery": true, "duration": 0.28, "status": "OK", "status_code": 200, "event": "issues", "action": "opened", "installation_id": 123, "repository_id": 456, "throttled_at": null } ]

Get a webhook delivery for an organization webhook

You must be an organization owner or have the "Manage organization webhooks" permission to use this endpoint.

OAuth app tokens and personal access tokens (classic) need admin:org_hook scope. OAuth apps cannot list, view, or edit webhooks that they did not create and users cannot list, view, or edit webhooks that were created by OAuth apps.

Fine-grained access tokens for "Get a webhook delivery for an organization webhook"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

  • "Webhooks" organization permissions (read)

Parameters for "Get a webhook delivery for an organization webhook"

Headers
Name, Type, Description
accept string

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

Path parameters
Name, Type, Description
org string Required

The organization name. The name is not case sensitive.

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.

delivery_id integer Required

HTTP response status codes for "Get a webhook delivery for an organization webhook"

Status codeDescription
200

OK

400

Bad Request

422

Validation failed, or the endpoint has been spammed.

Code samples for "Get a webhook delivery for an organization webhook"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

get/orgs/{org}/hooks/{hook_id}/deliveries/{delivery_id}
curl -L \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/orgs/ORG/hooks/HOOK_ID/deliveries/DELIVERY_ID

Response

Status: 200
{ "id": 12345678, "guid": "0b989ba4-242f-11e5-81e1-c7b6966d2516", "delivered_at": "2019-06-03T00:57:16Z", "redelivery": false, "duration": 0.27, "status": "OK", "status_code": 200, "event": "issues", "action": "opened", "installation_id": 123, "repository_id": 456, "url": "https://www.example.com", "throttled_at": "2019-06-03T00:57:16Z", "request": { "headers": { "X-GitHub-Delivery": "0b989ba4-242f-11e5-81e1-c7b6966d2516", "X-Hub-Signature-256": "sha256=6dcb09b5b57875f334f61aebed695e2e4193db5e", "Accept": "*/*", "X-GitHub-Hook-ID": "42", "User-Agent": "GitHub-Hookshot/b8c71d8", "X-GitHub-Event": "issues", "X-GitHub-Hook-Installation-Target-ID": "123", "X-GitHub-Hook-Installation-Target-Type": "repository", "content-type": "application/json", "X-Hub-Signature": "sha1=a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d" }, "payload": { "action": "opened", "issue": { "body": "foo" }, "repository": { "id": 123 } } }, "response": { "headers": { "Content-Type": "text/html;charset=utf-8" }, "payload": "ok" } }

Redeliver a delivery for an organization webhook

You must be an organization owner or have the "Manage organization webhooks" permission to use this endpoint.

OAuth app tokens and personal access tokens (classic) need admin:org_hook scope. OAuth apps cannot list, view, or edit webhooks that they did not create and users cannot list, view, or edit webhooks that were created by OAuth apps.

Fine-grained access tokens for "Redeliver a delivery for an organization webhook"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

  • "Webhooks" organization permissions (write)

Parameters for "Redeliver a delivery for an organization webhook"

Headers
Name, Type, Description
accept string

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

Path parameters
Name, Type, Description
org string Required

The organization name. The name is not case sensitive.

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.

delivery_id integer Required

HTTP response status codes for "Redeliver a delivery for an organization webhook"

Status codeDescription
202

Accepted

400

Bad Request

422

Validation failed, or the endpoint has been spammed.

Code samples for "Redeliver a delivery for an organization webhook"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

post/orgs/{org}/hooks/{hook_id}/deliveries/{delivery_id}/attempts
curl -L \ -X POST \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/orgs/ORG/hooks/HOOK_ID/deliveries/DELIVERY_ID/attempts

Accepted

Ping an organization webhook

You must be an organization owner or have the "Manage organization webhooks" permission to use this endpoint.

OAuth app tokens and personal access tokens (classic) need admin:org_hook scope. OAuth apps cannot list, view, or edit webhooks that they did not create and users cannot list, view, or edit webhooks that were created by OAuth apps.

Fine-grained access tokens for "Ping an organization webhook"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

  • "Webhooks" organization permissions (write)

Parameters for "Ping an organization webhook"

Headers
Name, Type, Description
accept string

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

Path parameters
Name, Type, Description
org string Required

The organization name. The name is not case sensitive.

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 an organization webhook"

Status codeDescription
204

No Content

404

Resource not found

Code samples for "Ping an organization webhook"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

post/orgs/{org}/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" \ https://api.github.com/orgs/ORG/hooks/HOOK_ID/pings

Response

Status: 204