存储库 Webhook 的 REST API 终结点
使用 REST API 创建和管理存储库的 Webhook。
关于存储库 Webhook
利用存储库 Webhook 可使你的服务器在存储库内发生特定事件时接收 HTTP POST
有效负载。 有关详细信息,请参阅“Webhook 文档”。
List repository webhooks
Lists webhooks for a repository. last response
may return null if there have not been any deliveries within 30 days.
“List repository webhooks”的细粒度访问令牌
此端点支持以下精细令牌类型:
精细令牌必须具有以下权限集:
- "Webhooks" repository permissions (read)
“List repository webhooks”的参数
名称, 类型, 说明 |
---|
accept string Setting to |
名称, 类型, 说明 |
---|
owner string 必须The account owner of the repository. The name is not case sensitive. |
repo string 必须The name of the repository without the |
名称, 类型, 说明 |
---|
per_page integer The number of results per page (max 100). For more information, see "Using pagination in the REST API." 默认: |
page integer The page number of the results to fetch. For more information, see "Using pagination in the REST API." 默认: |
“List repository webhooks”的 HTTP 响应状态代码
状态代码 | 说明 |
---|---|
200 | OK |
404 | Resource not found |
“List repository webhooks”的示例代码
如果你通过 GHE.com 访问 GitHub,请将 api.github.com
替换为你的企业在 api.SUBDOMAIN.ghe.com
上的专用子域。
请求示例
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/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",
"deliveries_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/deliveries",
"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.
“Create a repository webhook”的细粒度访问令牌
此端点支持以下精细令牌类型:
精细令牌必须具有以下权限集:
- "Webhooks" repository permissions (write)
“Create a repository webhook”的参数
名称, 类型, 说明 |
---|
accept string Setting to |
名称, 类型, 说明 |
---|
owner string 必须The account owner of the repository. The name is not case sensitive. |
repo string 必须The name of the repository without the |
名称, 类型, 说明 | |||||
---|---|---|---|---|---|
name string Use | |||||
config object Key/value pairs to provide settings for this webhook. | |||||
Properties of |
名称, 类型, 说明 |
---|
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 |
events
array of strings Determines what events the hook is triggered for.
默认: ["push"]
active
boolean Determines if notifications are sent when the webhook is triggered. Set to true
to send notifications.
默认: true
“Create a repository webhook”的 HTTP 响应状态代码
状态代码 | 说明 |
---|---|
201 | Created |
403 | Forbidden |
404 | Resource not found |
422 | Validation failed, or the endpoint has been spammed. |
“Create a repository webhook”的示例代码
如果你通过 GHE.com 访问 GitHub,请将 api.github.com
替换为你的企业在 api.SUBDOMAIN.ghe.com
上的专用子域。
请求示例
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/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",
"deliveries_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/deliveries",
"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."
“Get a repository webhook”的细粒度访问令牌
此端点支持以下精细令牌类型:
精细令牌必须具有以下权限集:
- "Webhooks" repository permissions (read)
“Get a repository webhook”的参数
名称, 类型, 说明 |
---|
accept string Setting to |
名称, 类型, 说明 |
---|
owner string 必须The account owner of the repository. The name is not case sensitive. |
repo string 必须The name of the repository without the |
hook_id integer 必须The unique identifier of the hook. You can find this value in the |
“Get a repository webhook”的 HTTP 响应状态代码
状态代码 | 说明 |
---|---|
200 | OK |
404 | Resource not found |
“Get a repository webhook”的示例代码
如果你通过 GHE.com 访问 GitHub,请将 api.github.com
替换为你的企业在 api.SUBDOMAIN.ghe.com
上的专用子域。
请求示例
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/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",
"deliveries_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/deliveries",
"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."
“Update a repository webhook”的细粒度访问令牌
此端点支持以下精细令牌类型:
精细令牌必须具有以下权限集:
- "Webhooks" repository permissions (write)
“Update a repository webhook”的参数
名称, 类型, 说明 |
---|
accept string Setting to |
名称, 类型, 说明 |
---|
owner string 必须The account owner of the repository. The name is not case sensitive. |
repo string 必须The name of the repository without the |
hook_id integer 必须The unique identifier of the hook. You can find this value in the |
名称, 类型, 说明 | |||||
---|---|---|---|---|---|
config object Configuration object of the webhook | |||||
Properties of |
名称, 类型, 说明 |
---|
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 |
events
array of strings Determines what events the hook is triggered for. This replaces the entire array of events.
默认: ["push"]
add_events
array of strings Determines a list of events to be added to the list of events that the Hook triggers for.
remove_events
array of strings Determines a list of events to be removed from the list of events that the Hook triggers for.
active
boolean Determines if notifications are sent when the webhook is triggered. Set to true
to send notifications.
默认: true
“Update a repository webhook”的 HTTP 响应状态代码
状态代码 | 说明 |
---|---|
200 | OK |
404 | Resource not found |
422 | Validation failed, or the endpoint has been spammed. |
“Update a repository webhook”的示例代码
如果你通过 GHE.com 访问 GitHub,请将 api.github.com
替换为你的企业在 api.SUBDOMAIN.ghe.com
上的专用子域。
请求示例
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/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",
"deliveries_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/deliveries",
"last_response": {
"code": null,
"status": "unused",
"message": null
}
}
Delete a repository webhook
“Delete a repository webhook”的细粒度访问令牌
此端点支持以下精细令牌类型:
精细令牌必须具有以下权限集:
- "Webhooks" repository permissions (write)
“Delete a repository webhook”的参数
名称, 类型, 说明 |
---|
accept string Setting to |
名称, 类型, 说明 |
---|
owner string 必须The account owner of the repository. The name is not case sensitive. |
repo string 必须The name of the repository without the |
hook_id integer 必须The unique identifier of the hook. You can find this value in the |
“Delete a repository webhook”的 HTTP 响应状态代码
状态代码 | 说明 |
---|---|
204 | No Content |
404 | Resource not found |
“Delete a repository webhook”的示例代码
如果你通过 GHE.com 访问 GitHub,请将 api.github.com
替换为你的企业在 api.SUBDOMAIN.ghe.com
上的专用子域。
请求示例
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/repos/OWNER/REPO/hooks/HOOK_ID
Response
Status: 204
Get a webhook configuration for a repository
Returns the webhook configuration for a repository. To get more information about the webhook, including the active
state and events
, use "Get a repository webhook."
OAuth app tokens and personal access tokens (classic) need the read:repo_hook
or repo
scope to use this endpoint.
“Get a webhook configuration for a repository”的细粒度访问令牌
此端点支持以下精细令牌类型:
精细令牌必须具有以下权限集:
- "Webhooks" repository permissions (read)
“Get a webhook configuration for a repository”的参数
名称, 类型, 说明 |
---|
accept string Setting to |
名称, 类型, 说明 |
---|
owner string 必须The account owner of the repository. The name is not case sensitive. |
repo string 必须The name of the repository without the |
hook_id integer 必须The unique identifier of the hook. You can find this value in the |
“Get a webhook configuration for a repository”的 HTTP 响应状态代码
状态代码 | 说明 |
---|---|
200 | OK |
“Get a webhook configuration for a repository”的示例代码
如果你通过 GHE.com 访问 GitHub,请将 api.github.com
替换为你的企业在 api.SUBDOMAIN.ghe.com
上的专用子域。
请求示例
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/repos/OWNER/REPO/hooks/HOOK_ID/config
Response
Update a webhook configuration for a repository
Updates the webhook configuration for a repository. To update more information about the webhook, including the active
state and events
, use "Update a repository webhook."
OAuth app tokens and personal access tokens (classic) need the write:repo_hook
or repo
scope to use this endpoint.
“Update a webhook configuration for a repository”的细粒度访问令牌
此端点支持以下精细令牌类型:
精细令牌必须具有以下权限集:
- "Webhooks" repository permissions (write)
“Update a webhook configuration for a repository”的参数
名称, 类型, 说明 |
---|
accept string Setting to |
名称, 类型, 说明 |
---|
owner string 必须The account owner of the repository. The name is not case sensitive. |
repo string 必须The name of the repository without the |
hook_id integer 必须The unique identifier of the hook. You can find this value in the |
名称, 类型, 说明 |
---|
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 |
“Update a webhook configuration for a repository”的 HTTP 响应状态代码
状态代码 | 说明 |
---|---|
200 | OK |
“Update a webhook configuration for a repository”的示例代码
如果你通过 GHE.com 访问 GitHub,请将 api.github.com
替换为你的企业在 api.SUBDOMAIN.ghe.com
上的专用子域。
请求示例
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/repos/OWNER/REPO/hooks/HOOK_ID/config \
-d '{"content_type":"json","url":"https://example.com/webhook"}'
Response
List deliveries for a repository webhook
Returns a list of webhook deliveries for a webhook configured in a repository.
“List deliveries for a repository webhook”的细粒度访问令牌
此端点支持以下精细令牌类型:
精细令牌必须具有以下权限集:
- "Webhooks" repository permissions (read)
“List deliveries for a repository webhook”的参数
名称, 类型, 说明 |
---|
accept string Setting to |
名称, 类型, 说明 |
---|
owner string 必须The account owner of the repository. The name is not case sensitive. |
repo string 必须The name of the repository without the |
hook_id integer 必须The unique identifier of the hook. You can find this value in the |
名称, 类型, 说明 |
---|
per_page integer The number of results per page (max 100). For more information, see "Using pagination in the REST API." 默认: |
cursor string Used for pagination: the starting delivery from which the page of deliveries is fetched. Refer to the |
“List deliveries for a repository webhook”的 HTTP 响应状态代码
状态代码 | 说明 |
---|---|
200 | OK |
400 | Bad Request |
422 | Validation failed, or the endpoint has been spammed. |
“List deliveries for a repository webhook”的示例代码
如果你通过 GHE.com 访问 GitHub,请将 api.github.com
替换为你的企业在 api.SUBDOMAIN.ghe.com
上的专用子域。
请求示例
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/repos/OWNER/REPO/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 delivery for a repository webhook
Returns a delivery for a webhook configured in a repository.
“Get a delivery for a repository webhook”的细粒度访问令牌
此端点支持以下精细令牌类型:
精细令牌必须具有以下权限集:
- "Webhooks" repository permissions (read)
“Get a delivery for a repository webhook”的参数
名称, 类型, 说明 |
---|
accept string Setting to |
名称, 类型, 说明 |
---|
owner string 必须The account owner of the repository. The name is not case sensitive. |
repo string 必须The name of the repository without the |
hook_id integer 必须The unique identifier of the hook. You can find this value in the |
delivery_id integer 必须 |
“Get a delivery for a repository webhook”的 HTTP 响应状态代码
状态代码 | 说明 |
---|---|
200 | OK |
400 | Bad Request |
422 | Validation failed, or the endpoint has been spammed. |
“Get a delivery for a repository webhook”的示例代码
如果你通过 GHE.com 访问 GitHub,请将 api.github.com
替换为你的企业在 api.SUBDOMAIN.ghe.com
上的专用子域。
请求示例
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/repos/OWNER/REPO/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 a repository webhook
Redeliver a webhook delivery for a webhook configured in a repository.
“Redeliver a delivery for a repository webhook”的细粒度访问令牌
此端点支持以下精细令牌类型:
精细令牌必须具有以下权限集:
- "Webhooks" repository permissions (write)
“Redeliver a delivery for a repository webhook”的参数
名称, 类型, 说明 |
---|
accept string Setting to |
名称, 类型, 说明 |
---|
owner string 必须The account owner of the repository. The name is not case sensitive. |
repo string 必须The name of the repository without the |
hook_id integer 必须The unique identifier of the hook. You can find this value in the |
delivery_id integer 必须 |
“Redeliver a delivery for a repository webhook”的 HTTP 响应状态代码
状态代码 | 说明 |
---|---|
202 | Accepted |
400 | Bad Request |
422 | Validation failed, or the endpoint has been spammed. |
“Redeliver a delivery for a repository webhook”的示例代码
如果你通过 GHE.com 访问 GitHub,请将 api.github.com
替换为你的企业在 api.SUBDOMAIN.ghe.com
上的专用子域。
请求示例
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/repos/OWNER/REPO/hooks/HOOK_ID/deliveries/DELIVERY_ID/attempts
Accepted
Ping a repository webhook
This will trigger a ping event to be sent to the hook.
“Ping a repository webhook”的细粒度访问令牌
此端点支持以下精细令牌类型:
精细令牌必须具有以下权限集:
- "Webhooks" repository permissions (read)
“Ping a repository webhook”的参数
名称, 类型, 说明 |
---|
accept string Setting to |
名称, 类型, 说明 |
---|
owner string 必须The account owner of the repository. The name is not case sensitive. |
repo string 必须The name of the repository without the |
hook_id integer 必须The unique identifier of the hook. You can find this value in the |
“Ping a repository webhook”的 HTTP 响应状态代码
状态代码 | 说明 |
---|---|
204 | No Content |
404 | Resource not found |
“Ping a repository webhook”的示例代码
如果你通过 GHE.com 访问 GitHub,请将 api.github.com
替换为你的企业在 api.SUBDOMAIN.ghe.com
上的专用子域。
请求示例
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/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
“Test the push repository webhook”的细粒度访问令牌
此端点支持以下精细令牌类型:
精细令牌必须具有以下权限集:
- "Webhooks" repository permissions (read)
“Test the push repository webhook”的参数
名称, 类型, 说明 |
---|
accept string Setting to |
名称, 类型, 说明 |
---|
owner string 必须The account owner of the repository. The name is not case sensitive. |
repo string 必须The name of the repository without the |
hook_id integer 必须The unique identifier of the hook. You can find this value in the |
“Test the push repository webhook”的 HTTP 响应状态代码
状态代码 | 说明 |
---|---|
204 | No Content |
404 | Resource not found |
“Test the push repository webhook”的示例代码
如果你通过 GHE.com 访问 GitHub,请将 api.github.com
替换为你的企业在 api.SUBDOMAIN.ghe.com
上的专用子域。
请求示例
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/repos/OWNER/REPO/hooks/HOOK_ID/tests
Response
Status: 204