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 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:
- GitHub App user access tokens
- GitHub App installation access tokens
- Fine-grained personal access tokens
The fine-grained token must have the following permission set:
- "Webhooks" organization permissions (read)
Parameters for "List organization webhooks"
Name, Type, Description |
---|
accept string Setting to |
Name, Type, Description |
---|
org string RequiredThe organization name. The name is not case sensitive. |
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: |
page integer The page number of the results to fetch. For more information, see "Using pagination in the REST API." Default: |
HTTP response status codes for "List organization webhooks"
Status code | Description |
---|---|
200 | OK |
404 | Resource not found |
Code samples for "List organization webhooks"
Request example
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/orgs/ORG/hooks
Response
Status: 200
[
{
"id": 1,
"url": "https://HOSTNAME/orgs/octocat/hooks/1",
"ping_url": "https://HOSTNAME/orgs/octocat/hooks/1/pings",
"deliveries_url": "https://HOSTNAME/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
Create a hook that posts payloads in JSON format.
You must be an organization owner 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:
- GitHub App user access tokens
- GitHub App installation access tokens
- Fine-grained personal access tokens
The fine-grained token must have the following permission set:
- "Webhooks" organization permissions (write)
Parameters for "Create an organization webhook"
Name, Type, Description |
---|
accept string Setting to |
Name, Type, Description |
---|
org string RequiredThe organization name. The name is not case sensitive. |
Name, Type, Description | |||||||
---|---|---|---|---|---|---|---|
name string RequiredMust be passed as "web". | |||||||
config object RequiredKey/value pairs to provide settings for this webhook. | |||||||
Properties of |
Name, Type, Description |
---|
url string RequiredThe URL to which the payloads will be delivered. |
content_type string The media type used to serialize the payloads. Supported values include |
secret string If provided, the |
insecure_ssl string or number Determines whether the SSL certificate of the host for |
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 code | Description |
---|---|
201 | Created |
404 | Resource not found |
422 | Validation failed, or the endpoint has been spammed. |
Code samples for "Create an organization webhook"
Request example
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/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://HOSTNAME/orgs/octocat/hooks/1",
"ping_url": "https://HOSTNAME/orgs/octocat/hooks/1/pings",
"deliveries_url": "https://HOSTNAME/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
Returns a webhook configured in an organization. To get only the webhook
config
properties, see "Get a webhook configuration for an organization.
You must be an organization owner 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:
- GitHub App user access tokens
- GitHub App installation access tokens
- Fine-grained personal access tokens
The fine-grained token must have the following permission set:
- "Webhooks" organization permissions (read)
Parameters for "Get an organization webhook"
Name, Type, Description |
---|
accept string Setting to |
Name, Type, Description |
---|
org string RequiredThe organization name. The name is not case sensitive. |
hook_id integer RequiredThe unique identifier of the hook. You can find this value in the |
HTTP response status codes for "Get an organization webhook"
Status code | Description |
---|---|
200 | OK |
404 | Resource not found |
Code samples for "Get an organization webhook"
Request example
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/orgs/ORG/hooks/HOOK_ID
Response
Status: 200
{
"id": 1,
"url": "https://HOSTNAME/orgs/octocat/hooks/1",
"ping_url": "https://HOSTNAME/orgs/octocat/hooks/1/pings",
"deliveries_url": "https://HOSTNAME/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
Updates a webhook configured in an organization. When you update a webhook,
the secret
will be overwritten. If you previously had a secret
set, you must
provide the same secret
or set a new secret
or the secret will be removed. If
you are only updating individual webhook config
properties, use "Update a webhook
configuration for an organization".
You must be an organization owner 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:
- GitHub App user access tokens
- GitHub App installation access tokens
- Fine-grained personal access tokens
The fine-grained token must have the following permission set:
- "Webhooks" organization permissions (write)
Parameters for "Update an organization webhook"
Name, Type, Description |
---|
accept string Setting to |
Name, Type, Description |
---|
org string RequiredThe organization name. The name is not case sensitive. |
hook_id integer RequiredThe unique identifier of the hook. You can find this value in the |
Name, Type, Description | |||||
---|---|---|---|---|---|
config object Key/value pairs to provide settings for this webhook. | |||||
Properties of |
Name, Type, Description |
---|
url string RequiredThe URL to which the payloads will be delivered. |
content_type string The media type used to serialize the payloads. Supported values include |
secret string If provided, the |
insecure_ssl string or number Determines whether the SSL certificate of the host for |
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 code | Description |
---|---|
200 | OK |
404 | Resource not found |
422 | Validation failed, or the endpoint has been spammed. |
Code samples for "Update an organization webhook"
Request example
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/orgs/ORG/hooks/HOOK_ID \
-d '{"active":true,"events":["pull_request"]}'
Response
Status: 200
{
"id": 1,
"url": "https://HOSTNAME/orgs/octocat/hooks/1",
"ping_url": "https://HOSTNAME/orgs/octocat/hooks/1/pings",
"deliveries_url": "https://HOSTNAME/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 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:
- GitHub App user access tokens
- GitHub App installation access tokens
- Fine-grained personal access tokens
The fine-grained token must have the following permission set:
- "Webhooks" organization permissions (write)
Parameters for "Delete an organization webhook"
Name, Type, Description |
---|
accept string Setting to |
Name, Type, Description |
---|
org string RequiredThe organization name. The name is not case sensitive. |
hook_id integer RequiredThe unique identifier of the hook. You can find this value in the |
HTTP response status codes for "Delete an organization webhook"
Status code | Description |
---|---|
204 | No Content |
404 | Resource not found |
Code samples for "Delete an organization webhook"
Request example
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/orgs/ORG/hooks/HOOK_ID
Response
Status: 204
Get a webhook configuration for an organization
Returns the webhook configuration for an organization. To get more information about the webhook, including the active
state and events
, use "Get an organization webhook ."
You must be an organization owner 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:
- GitHub App user access tokens
- GitHub App installation access tokens
- Fine-grained personal access tokens
The fine-grained token must have the following permission set:
- "Webhooks" organization permissions (read)
Parameters for "Get a webhook configuration for an organization"
Name, Type, Description |
---|
accept string Setting to |
Name, Type, Description |
---|
org string RequiredThe organization name. The name is not case sensitive. |
hook_id integer RequiredThe unique identifier of the hook. You can find this value in the |
HTTP response status codes for "Get a webhook configuration for an organization"
Status code | Description |
---|---|
200 | OK |
Code samples for "Get a webhook configuration for an organization"
Request example
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/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
Updates the webhook configuration for an organization. To update more information about the webhook, including the active
state and events
, use "Update an organization webhook ."
You must be an organization owner 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:
- GitHub App user access tokens
- GitHub App installation access tokens
- Fine-grained personal access tokens
The fine-grained token must have the following permission set:
- "Webhooks" organization permissions (write)
Parameters for "Update a webhook configuration for an organization"
Name, Type, Description |
---|
accept string Setting to |
Name, Type, Description |
---|
org string RequiredThe organization name. The name is not case sensitive. |
hook_id integer RequiredThe unique identifier of the hook. You can find this value in the |
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 |
secret string If provided, the |
insecure_ssl string or number Determines whether the SSL certificate of the host for |
HTTP response status codes for "Update a webhook configuration for an organization"
Status code | Description |
---|---|
200 | OK |
Code samples for "Update a webhook configuration for an organization"
Request example
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/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
Returns a list of webhook deliveries for a webhook configured in an organization.
You must be an organization owner 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:
- GitHub App user access tokens
- GitHub App installation access tokens
- Fine-grained personal access tokens
The fine-grained token must have the following permission set:
- "Webhooks" organization permissions (read)
Parameters for "List deliveries for an organization webhook"
Name, Type, Description |
---|
accept string Setting to |
Name, Type, Description |
---|
org string RequiredThe organization name. The name is not case sensitive. |
hook_id integer RequiredThe unique identifier of the hook. You can find this value in the |
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: |
cursor string Used for pagination: the starting delivery from which the page of deliveries is fetched. Refer to the |
redelivery boolean |
HTTP response status codes for "List deliveries for an organization webhook"
Status code | Description |
---|---|
200 | OK |
400 | Bad Request |
422 | Validation failed, or the endpoint has been spammed. |
Code samples for "List deliveries for an organization webhook"
Request example
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/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
Returns a delivery for a webhook configured in an organization.
You must be an organization owner 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:
- GitHub App user access tokens
- GitHub App installation access tokens
- Fine-grained personal access tokens
The fine-grained token must have the following permission set:
- "Webhooks" organization permissions (read)
Parameters for "Get a webhook delivery for an organization webhook"
Name, Type, Description |
---|
accept string Setting to |
Name, Type, Description |
---|
org string RequiredThe organization name. The name is not case sensitive. |
hook_id integer RequiredThe unique identifier of the hook. You can find this value in the |
delivery_id integer Required |
HTTP response status codes for "Get a webhook delivery for an organization webhook"
Status code | Description |
---|---|
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"
Request example
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/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
Redeliver a delivery for a webhook configured in an organization.
You must be an organization owner 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:
- GitHub App user access tokens
- GitHub App installation access tokens
- Fine-grained personal access tokens
The fine-grained token must have the following permission set:
- "Webhooks" organization permissions (write)
Parameters for "Redeliver a delivery for an organization webhook"
Name, Type, Description |
---|
accept string Setting to |
Name, Type, Description |
---|
org string RequiredThe organization name. The name is not case sensitive. |
hook_id integer RequiredThe unique identifier of the hook. You can find this value in the |
delivery_id integer Required |
HTTP response status codes for "Redeliver a delivery for an organization webhook"
Status code | Description |
---|---|
202 | Accepted |
400 | Bad Request |
422 | Validation failed, or the endpoint has been spammed. |
Code samples for "Redeliver a delivery for an organization webhook"
Request example
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/orgs/ORG/hooks/HOOK_ID/deliveries/DELIVERY_ID/attempts
Accepted
Status: 202
Ping an organization webhook
This will trigger a ping event to be sent to the hook.
You must be an organization owner 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:
- GitHub App user access tokens
- GitHub App installation access tokens
- Fine-grained personal access tokens
The fine-grained token must have the following permission set:
- "Webhooks" organization permissions (write)
Parameters for "Ping an organization webhook"
Name, Type, Description |
---|
accept string Setting to |
Name, Type, Description |
---|
org string RequiredThe organization name. The name is not case sensitive. |
hook_id integer RequiredThe unique identifier of the hook. You can find this value in the |
HTTP response status codes for "Ping an organization webhook"
Status code | Description |
---|---|
204 | No Content |
404 | Resource not found |
Code samples for "Ping an organization webhook"
Request example
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/orgs/ORG/hooks/HOOK_ID/pings
Response
Status: 204