This version of GitHub Enterprise was discontinued on 2022-06-03. No patch releases will be made, even for critical security issues. For better performance, improved security, and new features, upgrade to the latest version of GitHub Enterprise. For help with the upgrade, contact GitHub Enterprise support.
We've recently moved some of the REST API documentation. If you can't find what you're looking for, you might try the new Branches, Collaborators, Commits, Deploy Keys, Deployments, GitHub Pages, Releases, Metrics, Webhooks REST API pages.
Repository Webhooks
List repository webhooks
Parameters
Headers |
---|
Name, Type, Description |
accept stringSetting to |
Path parameters |
Name, Type, Description |
owner stringRequiredThe account owner of the repository. The name is not case sensitive. |
repo stringRequiredThe name of the repository. The name is not case sensitive. |
Query parameters |
Name, Type, Description |
per_page integerThe number of results per page (max 100). Default: |
page integerPage number of the results to fetch. Default: |
HTTP response status codes
Status code | Description |
---|---|
200 | OK |
404 | Resource not found |
Code samples
curl \
-H "Accept: application/vnd.github.v3+json" \
-H "Authorization: token <TOKEN>" \
http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/hooks
Response
Status: 200
[
{
"type": "Repository",
"id": 12345678,
"name": "web",
"active": true,
"events": [
"push",
"pull_request"
],
"config": {
"content_type": "json",
"insecure_ssl": "0",
"url": "https://example.com/webhook"
},
"updated_at": "2019-06-03T00:57:16Z",
"created_at": "2019-06-03T00:57:16Z",
"url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678",
"test_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/test",
"ping_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/pings",
"last_response": {
"code": null,
"status": "unused",
"message": null
}
}
]
Create a repository webhook
Repositories can have multiple webhooks installed. Each webhook should have a unique config
. Multiple webhooks can
share the same config
as long as those webhooks do not have any events
that overlap.
Parameters
Headers | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
Name, Type, Description | ||||||||||
accept stringSetting to | ||||||||||
Path parameters | ||||||||||
Name, Type, Description | ||||||||||
owner stringRequiredThe account owner of the repository. The name is not case sensitive. | ||||||||||
repo stringRequiredThe name of the repository. The name is not case sensitive. | ||||||||||
Body parameters | ||||||||||
Name, Type, Description | ||||||||||
name stringUse | ||||||||||
config objectKey/value pairs to provide settings for this webhook. These are defined below. | ||||||||||
Properties of the |
Name, Type, Description |
---|
url stringThe URL to which the payloads will be delivered. |
content_type stringThe media type used to serialize the payloads. Supported values include |
secret stringIf provided, the |
insecure_ssl string or number or Determines whether the SSL certificate of the host for |
token string |
digest string |
events
array of stringsDetermines what events the hook is triggered for.
Default: push
active
booleanDetermines if notifications are sent when the webhook is triggered. Set to true
to send notifications.
Default: true
HTTP response status codes
Status code | Description |
---|---|
201 | Created |
403 | Forbidden |
404 | Resource not found |
422 | Validation failed |
Code samples
curl \
-X POST \
-H "Accept: application/vnd.github.v3+json" \
-H "Authorization: token <TOKEN>" \
http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/hooks \
-d '{"name":"web","active":true,"events":["push","pull_request"],"config":{"url":"https://example.com/webhook","content_type":"json","insecure_ssl":"0"}}'
Response
Status: 201
{
"type": "Repository",
"id": 12345678,
"name": "web",
"active": true,
"events": [
"push",
"pull_request"
],
"config": {
"content_type": "json",
"insecure_ssl": "0",
"url": "https://example.com/webhook"
},
"updated_at": "2019-06-03T00:57:16Z",
"created_at": "2019-06-03T00:57:16Z",
"url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678",
"test_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/test",
"ping_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/pings",
"last_response": {
"code": null,
"status": "unused",
"message": null
}
}
Get a repository webhook
Returns a webhook configured in a repository. To get only the webhook config
properties, see "Get a webhook configuration for a repository."
Parameters
Headers |
---|
Name, Type, Description |
accept stringSetting to |
Path parameters |
Name, Type, Description |
owner stringRequiredThe account owner of the repository. The name is not case sensitive. |
repo stringRequiredThe name of the repository. The name is not case sensitive. |
hook_id integerRequiredThe unique identifier of the hook. |
HTTP response status codes
Status code | Description |
---|---|
200 | OK |
404 | Resource not found |
Code samples
curl \
-H "Accept: application/vnd.github.v3+json" \
-H "Authorization: token <TOKEN>" \
http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/hooks/HOOK_ID
Response
Status: 200
{
"type": "Repository",
"id": 12345678,
"name": "web",
"active": true,
"events": [
"push",
"pull_request"
],
"config": {
"content_type": "json",
"insecure_ssl": "0",
"url": "https://example.com/webhook"
},
"updated_at": "2019-06-03T00:57:16Z",
"created_at": "2019-06-03T00:57:16Z",
"url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678",
"test_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/test",
"ping_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/pings",
"last_response": {
"code": null,
"status": "unused",
"message": null
}
}
Update a repository webhook
Updates a webhook configured in a repository. 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 a repository."
Parameters
Headers | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
Name, Type, Description | ||||||||||
accept stringSetting to | ||||||||||
Path parameters | ||||||||||
Name, Type, Description | ||||||||||
owner stringRequiredThe account owner of the repository. The name is not case sensitive. | ||||||||||
repo stringRequiredThe name of the repository. The name is not case sensitive. | ||||||||||
hook_id integerRequiredThe unique identifier of the hook. | ||||||||||
Body parameters | ||||||||||
Name, Type, Description | ||||||||||
config objectKey/value pairs to provide settings for this webhook. These are defined below. | ||||||||||
Properties of the |
Name, Type, Description |
---|
url stringRequiredThe URL to which the payloads will be delivered. |
content_type stringThe media type used to serialize the payloads. Supported values include |
secret stringIf provided, the |
insecure_ssl string or number or Determines whether the SSL certificate of the host for |
address string |
room string |
events
array of stringsDetermines what events the hook is triggered for. This replaces the entire array of events.
Default: push
add_events
array of stringsDetermines a list of events to be added to the list of events that the Hook triggers for.
remove_events
array of stringsDetermines a list of events to be removed from the list of events that the Hook triggers for.
active
booleanDetermines if notifications are sent when the webhook is triggered. Set to true
to send notifications.
Default: true
HTTP response status codes
Status code | Description |
---|---|
200 | OK |
404 | Resource not found |
422 | Validation failed |
Code samples
curl \
-X PATCH \
-H "Accept: application/vnd.github.v3+json" \
-H "Authorization: token <TOKEN>" \
http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/hooks/HOOK_ID \
-d '{"active":true,"add_events":["pull_request"]}'
Response
Status: 200
{
"type": "Repository",
"id": 12345678,
"name": "web",
"active": true,
"events": [
"push",
"pull_request"
],
"config": {
"content_type": "json",
"insecure_ssl": "0",
"url": "https://example.com/webhook"
},
"updated_at": "2019-06-03T00:57:16Z",
"created_at": "2019-06-03T00:57:16Z",
"url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678",
"test_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/test",
"ping_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/pings",
"last_response": {
"code": null,
"status": "unused",
"message": null
}
}
Delete a repository webhook
Parameters
Headers |
---|
Name, Type, Description |
accept stringSetting to |
Path parameters |
Name, Type, Description |
owner stringRequiredThe account owner of the repository. The name is not case sensitive. |
repo stringRequiredThe name of the repository. The name is not case sensitive. |
hook_id integerRequiredThe unique identifier of the hook. |
HTTP response status codes
Status code | Description |
---|---|
204 | No Content |
404 | Resource not found |
Code samples
curl \
-X DELETE \
-H "Accept: application/vnd.github.v3+json" \
-H "Authorization: token <TOKEN>" \
http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/hooks/HOOK_ID
Response
Status: 204
Ping a repository webhook
This will trigger a ping event to be sent to the hook.
Parameters
Headers |
---|
Name, Type, Description |
accept stringSetting to |
Path parameters |
Name, Type, Description |
owner stringRequiredThe account owner of the repository. The name is not case sensitive. |
repo stringRequiredThe name of the repository. The name is not case sensitive. |
hook_id integerRequiredThe unique identifier of the hook. |
HTTP response status codes
Status code | Description |
---|---|
204 | No Content |
404 | Resource not found |
Code samples
curl \
-X POST \
-H "Accept: application/vnd.github.v3+json" \
-H "Authorization: token <TOKEN>" \
http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/hooks/HOOK_ID/pings
Response
Status: 204
Test the push repository webhook
This will trigger the hook with the latest push to the current repository if the hook is subscribed to push
events. If the hook is not subscribed to push
events, the server will respond with 204 but no test POST will be generated.
Note: Previously /repos/:owner/:repo/hooks/:hook_id/test
Parameters
Headers |
---|
Name, Type, Description |
accept stringSetting to |
Path parameters |
Name, Type, Description |
owner stringRequiredThe account owner of the repository. The name is not case sensitive. |
repo stringRequiredThe name of the repository. The name is not case sensitive. |
hook_id integerRequiredThe unique identifier of the hook. |
HTTP response status codes
Status code | Description |
---|---|
204 | No Content |
404 | Resource not found |
Code samples
curl \
-X POST \
-H "Accept: application/vnd.github.v3+json" \
-H "Authorization: token <TOKEN>" \
http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/hooks/HOOK_ID/tests
Response
Status: 204