REST API 现在已版本化。 有关更多信息，请参阅 "关于 API 版本控制."

用于仓库 Webhook 的 REST API 端点

使用 REST API 为您的仓库创建和管理 Webhook。

关于仓库 Webhook

仓库 Webhook 允许您的服务器在仓库中发生特定事件时接收 HTTP POST 负载。有关更多信息，请参阅 "Webhook 文档."

列出仓库 Webhook

列出仓库的 Webhook。如果 30 天内没有交付，last response 可能会返回 null。

用于“列出仓库 Webhook”的细粒度访问令牌

此端点适用于以下细粒度令牌类型

细粒度令牌必须具有以下权限集

  • “Webhook”仓库权限（读取）

用于“列出仓库 Webhook”的参数

标头
accept string

建议设置为 application/vnd.github+json。

路径参数
owner string 必需

仓库的帐户所有者。名称不区分大小写。

repo string 必需

仓库的名称，不包含 .git 扩展名。名称不区分大小写。

查询参数
per_page integer

每页结果数（最大 100）。有关更多信息，请参阅 "在 REST API 中使用分页."

默认: 30

page integer

要获取的结果页码。有关更多信息，请参阅 "在 REST API 中使用分页."

默认: 1

用于“列出仓库 Webhook”的 HTTP 响应状态码

状态码描述
200

OK

404

资源未找到

用于“列出仓库 Webhook”的代码示例

请求示例

get/repos/{owner}/{repo}/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/repos/OWNER/REPO/hooks

响应

状态：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 } } ]

创建仓库 Webhook

仓库可以安装多个 Webhook。每个 Webhook 应该具有唯一的 config。多个 Webhook 可以共享相同的 config，只要这些 Webhook 没有任何重叠的 events。

用于“创建仓库 Webhook”的细粒度访问令牌

此端点适用于以下细粒度令牌类型

细粒度令牌必须具有以下权限集

  • “Webhooks”仓库权限（写入）

用于“创建仓库 Webhook”的参数

标头
accept string

建议设置为 application/vnd.github+json。

路径参数
owner string 必需

仓库的帐户所有者。名称不区分大小写。

repo string 必需

仓库的名称，不包含 .git 扩展名。名称不区分大小写。

主体参数
name 字符串

使用 web 创建 Webhook。默认值：web。此参数仅接受值 web。

config 对象

键值对，用于提供此 Webhook 的设置。

url 字符串

将要传递有效负载的 URL。

content_type 字符串

用于序列化有效负载的媒体类型。支持的值包括 json 和 form。默认值为 form。

secret 字符串

如果提供，secret 将用作生成 传递签名头 的 HMAC 十六进制摘要值的 key。

insecure_ssl 字符串或数字

确定在传递有效负载时是否将验证 url 主机的 SSL 证书。支持的值包括 0（执行验证）和 1（不执行验证）。默认值为 0。我们强烈建议不要将其设置为 1，因为您可能会受到中间人攻击和其他攻击。

events 字符串数组

确定触发钩子的事件。

默认: ["push"]

active 布尔值

确定触发 Webhook 时是否发送通知。设置为 true 以发送通知。

默认: true

“创建仓库 Webhook” 的 HTTP 响应状态码

状态码描述
201

已创建

403

禁止

404

资源未找到

422

验证失败，或端点已被垃圾邮件轰炸。

“创建仓库 Webhook” 的代码示例

请求示例

post/repos/{owner}/{repo}/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/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"}}'

响应

状态：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 } }

获取仓库 Webhook

返回在仓库中配置的 Webhook。要仅获取 Webhook config 属性，请参阅“获取仓库的 Webhook 配置”。

“获取仓库 Webhook” 的细粒度访问令牌

此端点适用于以下细粒度令牌类型

细粒度令牌必须具有以下权限集

  • “Webhook”仓库权限（读取）

“获取仓库 Webhook” 的参数

标头
accept string

建议设置为 application/vnd.github+json。

路径参数
owner string 必需

仓库的帐户所有者。名称不区分大小写。

repo string 必需

仓库的名称，不包含 .git 扩展名。名称不区分大小写。

hook_id 整数 必需

钩子的唯一标识符。您可以在 Webhook 传递的 X-GitHub-Hook-ID 标头中找到此值。

“获取仓库 Webhook” 的 HTTP 响应状态码

状态码描述
200

OK

404

资源未找到

“获取仓库 Webhook” 的代码示例

请求示例

get/repos/{owner}/{repo}/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/repos/OWNER/REPO/hooks/HOOK_ID

响应

状态：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 } }

更新仓库 Webhook

更新仓库中配置的 Webhook。如果您之前设置了 `secret`，则必须提供相同的 `secret` 或设置新的 `secret`，否则将删除该 secret。如果您只是更新单个 Webhook `config` 属性，请使用 "更新仓库的 Webhook 配置。"。

“更新仓库 Webhook”的细粒度访问令牌

此端点适用于以下细粒度令牌类型

细粒度令牌必须具有以下权限集

  • “Webhooks”仓库权限（写入）

“更新仓库 Webhook”的参数

标头
accept string

建议设置为 application/vnd.github+json。

路径参数
owner string 必需

仓库的帐户所有者。名称不区分大小写。

repo string 必需

仓库的名称，不包含 .git 扩展名。名称不区分大小写。

hook_id 整数 必需

钩子的唯一标识符。您可以在 Webhook 传递的 X-GitHub-Hook-ID 标头中找到此值。

主体参数
config 对象

Webhook 的配置对象

url 字符串

将要传递有效负载的 URL。

content_type 字符串

用于序列化有效负载的媒体类型。支持的值包括 json 和 form。默认值为 form。

secret 字符串

如果提供，secret 将用作生成 传递签名头 的 HMAC 十六进制摘要值的 key。

insecure_ssl 字符串或数字

确定在传递有效负载时是否将验证 url 主机的 SSL 证书。支持的值包括 0（执行验证）和 1（不执行验证）。默认值为 0。我们强烈建议不要将其设置为 1，因为您可能会受到中间人攻击和其他攻击。

events 字符串数组

确定 Hook 触发的 事件。这将替换整个事件数组。

默认: ["push"]

add_events 字符串数组

确定要添加到 Hook 触发的事件列表中的事件列表。

remove_events 字符串数组

确定要从 Hook 触发的事件列表中删除的事件列表。

active 布尔值

确定触发 Webhook 时是否发送通知。设置为 true 以发送通知。

默认: true

“更新仓库 Webhook”的 HTTP 响应状态码

状态码描述
200

OK

404

资源未找到

422

验证失败，或端点已被垃圾邮件轰炸。

“更新仓库 Webhook”的代码示例

请求示例

patch/repos/{owner}/{repo}/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/repos/OWNER/REPO/hooks/HOOK_ID \ -d '{"active":true,"add_events":["pull_request"]}'

响应

状态：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 } }

删除仓库 Webhook

“删除仓库 Webhook”的细粒度访问令牌

此端点适用于以下细粒度令牌类型

细粒度令牌必须具有以下权限集

  • “Webhooks”仓库权限（写入）

“删除仓库 Webhook”的参数

标头
accept string

建议设置为 application/vnd.github+json。

路径参数
owner string 必需

仓库的帐户所有者。名称不区分大小写。

repo string 必需

仓库的名称，不包含 .git 扩展名。名称不区分大小写。

hook_id 整数 必需

钩子的唯一标识符。您可以在 Webhook 传递的 X-GitHub-Hook-ID 标头中找到此值。

“删除仓库 Webhook”的 HTTP 响应状态码

状态码描述
204

无内容

404

资源未找到

“删除仓库 Webhook”的代码示例

请求示例

delete/repos/{owner}/{repo}/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/repos/OWNER/REPO/hooks/HOOK_ID

响应

状态：204

获取仓库的 Webhook 配置

返回仓库的 Webhook 配置。要获取有关 Webhook 的更多信息，包括 `active` 状态和 `events`，请使用 "获取仓库 Webhook。"。

OAuth 应用程序令牌和个人访问令牌（经典）需要 `read:repo_hook` 或 `repo` 范围才能使用此端点。

“获取仓库的 Webhook 配置”的细粒度访问令牌

此端点适用于以下细粒度令牌类型

细粒度令牌必须具有以下权限集

  • “Webhook”仓库权限（读取）

获取仓库 Webhook 配置的参数

标头
accept string

建议设置为 application/vnd.github+json。

路径参数
owner string 必需

仓库的帐户所有者。名称不区分大小写。

repo string 必需

仓库的名称，不包含 .git 扩展名。名称不区分大小写。

hook_id 整数 必需

钩子的唯一标识符。您可以在 Webhook 传递的 X-GitHub-Hook-ID 标头中找到此值。

获取仓库 Webhook 配置的 HTTP 响应状态码

状态码描述
200

OK

获取仓库 Webhook 配置的代码示例

请求示例

get/repos/{owner}/{repo}/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/repos/OWNER/REPO/hooks/HOOK_ID/config

响应

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

更新仓库 Webhook 配置

更新仓库的 Webhook 配置。要更新有关 Webhook 的更多信息，包括 `active` 状态和 `events`，请使用 "更新仓库 Webhook."

OAuth 应用令牌和个人访问令牌（经典）需要 `write:repo_hook` 或 `repo` 范围才能使用此端点。

更新仓库 Webhook 配置的细粒度访问令牌

此端点适用于以下细粒度令牌类型

细粒度令牌必须具有以下权限集

  • “Webhooks”仓库权限（写入）

更新仓库 Webhook 配置的参数

标头
accept string

建议设置为 application/vnd.github+json。

路径参数
owner string 必需

仓库的帐户所有者。名称不区分大小写。

repo string 必需

仓库的名称，不包含 .git 扩展名。名称不区分大小写。

hook_id 整数 必需

钩子的唯一标识符。您可以在 Webhook 传递的 X-GitHub-Hook-ID 标头中找到此值。

主体参数
url 字符串

将要传递有效负载的 URL。

content_type 字符串

用于序列化有效负载的媒体类型。支持的值包括 json 和 form。默认值为 form。

secret 字符串

如果提供，secret 将用作生成 传递签名头 的 HMAC 十六进制摘要值的 key。

insecure_ssl 字符串或数字

确定在传递有效负载时是否将验证 url 主机的 SSL 证书。支持的值包括 0（执行验证）和 1（不执行验证）。默认值为 0。我们强烈建议不要将其设置为 1，因为您可能会受到中间人攻击和其他攻击。

更新仓库 Webhook 配置的 HTTP 响应状态码

状态码描述
200

OK

更新仓库 Webhook 配置的代码示例

请求示例

patch/repos/{owner}/{repo}/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/repos/OWNER/REPO/hooks/HOOK_ID/config \ -d '{"content_type":"json","url":"https://example.com/webhook"}'

响应

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

列出仓库 Webhook 的传递

返回仓库中配置的 Webhook 的 Webhook 传递列表。

列出仓库 Webhook 传递的细粒度访问令牌

此端点适用于以下细粒度令牌类型

细粒度令牌必须具有以下权限集

  • “Webhook”仓库权限（读取）

列出仓库 Webhook 传递的参数

标头
accept string

建议设置为 application/vnd.github+json。

路径参数
owner string 必需

仓库的帐户所有者。名称不区分大小写。

repo string 必需

仓库的名称，不包含 .git 扩展名。名称不区分大小写。

hook_id 整数 必需

钩子的唯一标识符。您可以在 Webhook 传递的 X-GitHub-Hook-ID 标头中找到此值。

查询参数
per_page integer

每页结果数（最大 100）。有关更多信息，请参阅 "在 REST API 中使用分页."

默认: 30

cursor string

用于分页：获取传递页面的起始传递。有关下一页和上一页游标，请参阅 `link` 标头。

redelivery boolean

列出仓库 Webhook 传递的 HTTP 响应状态码

状态码描述
200

OK

400

错误请求

422

验证失败，或端点已被垃圾邮件轰炸。

“列出仓库 Webhook 的交付”代码示例

请求示例

get/repos/{owner}/{repo}/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/repos/OWNER/REPO/hooks/HOOK_ID/deliveries

响应

状态：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 } ]

获取仓库 Webhook 的交付

返回在仓库中配置的 Webhook 的交付。

“获取仓库 Webhook 的交付”的细粒度访问令牌

此端点适用于以下细粒度令牌类型

细粒度令牌必须具有以下权限集

  • “Webhook”仓库权限（读取）

“获取仓库 Webhook 的交付”的参数

标头
accept string

建议设置为 application/vnd.github+json。

路径参数
owner string 必需

仓库的帐户所有者。名称不区分大小写。

repo string 必需

仓库的名称，不包含 .git 扩展名。名称不区分大小写。

hook_id 整数 必需

钩子的唯一标识符。您可以在 Webhook 传递的 X-GitHub-Hook-ID 标头中找到此值。

delivery_id integer 必需

“获取仓库 Webhook 的交付”的 HTTP 响应状态码

状态码描述
200

OK

400

错误请求

422

验证失败，或端点已被垃圾邮件轰炸。

“获取仓库 Webhook 的交付”代码示例

请求示例

get/repos/{owner}/{repo}/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/repos/OWNER/REPO/hooks/HOOK_ID/deliveries/DELIVERY_ID

响应

状态：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" } }

重新发送仓库 Webhook 的交付

重新发送在仓库中配置的 Webhook 的交付。

“重新发送仓库 Webhook 的交付”的细粒度访问令牌

此端点适用于以下细粒度令牌类型

细粒度令牌必须具有以下权限集

  • “Webhooks”仓库权限（写入）

“重新发送仓库 Webhook 的交付”的参数

标头
accept string

建议设置为 application/vnd.github+json。

路径参数
owner string 必需

仓库的帐户所有者。名称不区分大小写。

repo string 必需

仓库的名称，不包含 .git 扩展名。名称不区分大小写。

hook_id 整数 必需

钩子的唯一标识符。您可以在 Webhook 传递的 X-GitHub-Hook-ID 标头中找到此值。

delivery_id integer 必需

“重新发送仓库 Webhook 的交付”的 HTTP 响应状态码

状态码描述
202

已接受

400

错误请求

422

验证失败，或端点已被垃圾邮件轰炸。

“重新发送仓库 Webhook 的交付”的代码示例

请求示例

post/repos/{owner}/{repo}/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/repos/OWNER/REPO/hooks/HOOK_ID/deliveries/DELIVERY_ID/attempts

已接受

状态：202

Ping 仓库 Webhook

这将触发发送到钩子的 ping 事件。

“Ping 仓库 Webhook”的细粒度访问令牌

此端点适用于以下细粒度令牌类型

细粒度令牌必须具有以下权限集

  • “Webhook”仓库权限（读取）

“Ping 仓库 Webhook”的参数

标头
accept string

建议设置为 application/vnd.github+json。

路径参数
owner string 必需

仓库的帐户所有者。名称不区分大小写。

repo string 必需

仓库的名称，不包含 .git 扩展名。名称不区分大小写。

hook_id 整数 必需

钩子的唯一标识符。您可以在 Webhook 传递的 X-GitHub-Hook-ID 标头中找到此值。

“Ping 仓库 Webhook”的 HTTP 响应状态码

状态码描述
204

无内容

404

资源未找到

“Ping 仓库 Webhook”的代码示例

请求示例

post/repos/{owner}/{repo}/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/repos/OWNER/REPO/hooks/HOOK_ID/pings

响应

状态：204

测试推送仓库 Webhook

如果钩子订阅了 push 事件，这将使用对当前仓库的最新推送触发钩子。如果钩子没有订阅 push 事件，服务器将以 204 响应，但不会生成测试 POST。

注意：以前为 /repos/:owner/:repo/hooks/:hook_id/test

“测试推送仓库 Webhook”的细粒度访问令牌

此端点适用于以下细粒度令牌类型

细粒度令牌必须具有以下权限集

  • “Webhook”仓库权限（读取）

“测试推送仓库 Webhook”的参数

标头
accept string

建议设置为 application/vnd.github+json。

路径参数
owner string 必需

仓库的帐户所有者。名称不区分大小写。

repo string 必需

仓库的名称，不包含 .git 扩展名。名称不区分大小写。

hook_id 整数 必需

钩子的唯一标识符。您可以在 Webhook 传递的 X-GitHub-Hook-ID 标头中找到此值。

“测试推送仓库 Webhook”的 HTTP 响应状态码

状态码描述
204

无内容

404

资源未找到

“测试推送仓库 Webhook”的代码示例

请求示例

post/repos/{owner}/{repo}/hooks/{hook_id}/tests
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

响应

状态：204