Webhook 事件和有效负载

了解每个 Webhook 事件发生的时间以及有效负载包含的内容。

在本文中

有关 Webhook 事件和有效负载

您可以创建订阅此页所列事件的 web 挂钩。 若要限制对服务器的 HTTP 请求数，应仅订阅计划处理的特定事件。 有关详细信息，请参阅“创建网络钩子”。

此页面上的每个 Webhook 事件都包含该事件的 Webhook 属性的说明。 如果某个事件包含多个操作，则会包含与每个操作对应的属性。

每个事件仅适用于特定类型的 Webhook。 例如，组织 Webhook 可以订阅 team 事件，但存储库 Webhook 无法订阅。 各个 Webhook 事件的说明中列出该事件的可用性。 有关详细信息，请参阅“Webhook 的类型”。

sender 属性

大多数 Webhook 的有效负载都包含一个名为 sender 的属性，用于标识触发该事件的用户。 GitHub有时无法解析特定用户，例如，当事件来自内部进程而不是人员或触发操作没有关联用户时。 对于某些事件，例如 check_run 和 check_suite，这包括没有 Git 推送或经过身份验证的 API 参与者的操作。

在这些情况下，sender 会填入 ghost 用户，这是一个占位账户，其 login 为 ghost，并且其 id 不与真实的当前用户关联。 不要假设 sender 始终标识的是触发事件的人，并在任何依赖它的安全或业务逻辑中将 ghost 用户考虑在内。

有效负载上限

有效负载上限为 25 MB。 如果事件生成的有效负载较大，GitHub 将不会为该 Webhook 事件传递有效负载。 例如，如果同时推送多个分支或标记，这种情况可能会发生在 create 事件中。 我们建议监控有效负载的大小以确保成功递送。

"传输标头"

通过 HTTP POST 方式递送到您的 Webhook 配置的 URL 端点的有效负载将包含几个特殊标头。

  • X-GitHub-Hook-ID：Webhook 的唯一标识符。
  • X-GitHub-Event：触发传递的事件的名称。
  • X-GitHub-Delivery：用于标识事件的全局唯一标识符（GUID）。
  • X-Hub-Signature：如果 Webhook 配置了 secret，则会发送此标头。 这是请求正文的 HMAC 十六进制摘要，使用 SHA-1 哈希函数，并以 secret 作为 HMAC key 生成。 提供 X-Hub-Signature 以便与现有集成兼容。 建议改用更加安全的 X-Hub-Signature-256。
  • X-Hub-Signature-256：如果 Webhook 配置了 secret，则会发送此标头。 这是请求正文的 HMAC 十六进制摘要，使用 SHA-256 哈希函数并以 secret 作为 HMAC key 生成。 有关详细信息，请参阅“验证 Webhook 交付”。
  • User-Agent：此标头将始终具有前缀 GitHub-Hookshot/。
  • X-GitHub-Hook-Installation-Target-Type：创建 webhook 的资源类型。
  • X-GitHub-Hook-Installation-Target-ID：创建 Webhook 的资源的唯一标识符。

若要查看每个标头在 Webhook 有效负载中可能呈现的内容，请参阅 Webhook 交付示例。

Webhook交付示例

可以选择将有效负载以 JSON 格式 (application/json) 或作为 URL 编码数据 (x-www-form-urlencoded) 传递。 下面是一个使用 JSON 格式的 Webhook POST 请求的示例。

> POST /payload HTTP/1.1

> X-GitHub-Delivery: 72d3162e-cc78-11e3-81ab-4c9367dc0958
> X-Hub-Signature: sha1=7d38cdd689735b008b3c702edd92eea23791c5f6
> X-Hub-Signature-256: sha256=d57c68ca6f92289e6987922ff26938930f6e66a2d161ef06abdf1859230aa23c
> User-Agent: GitHub-Hookshot/044aadd
> Content-Type: application/json
> Content-Length: 6615
> X-GitHub-Event: issues
> X-GitHub-Hook-ID: 292430182
> X-GitHub-Hook-Installation-Target-ID: 79929171
> X-GitHub-Hook-Installation-Target-Type: repository

> {
>   "action": "opened",
>   "issue": {
>     "url": "https://api.github.com/repos/octocat/Hello-World/issues/1347",
>     "number": 1347,
>     ...
>   },
>   "repository" : {
>     "id": 1296269,
>     "full_name": "octocat/Hello-World",
>     "owner": {
>       "login": "octocat",
>       "id": 1,
>       ...
>     },
>     ...
>   },
>   "sender": {
>     "login": "octocat",
>     "id": 1,
>     ...
>   }
> }

branch_protection_configuration

This event occurs when there is a change to branch protection configurations for a repository. For more information, see "About protected branches." For information about using the APIs to manage branch protection rules, see "Branch protection rule" in the GraphQL documentation or "Branch protection" in the REST API documentation.

To subscribe to this event, a GitHub App must have at least read-level access for the "Administration" repository permission.

branch_protection_configuration 的可用性

  • 存储库
  • 组织
  • GitHub应用

branch_protection_configuration 的 Webhook 有效负载对象

All branch protections were disabled for a repository.

Webhook 请求正文参数
action string 必须

值: disabled

enterprise object

An enterprise on GitHub. Webhook payloads contain the enterprise property when the webhook is configured on an enterprise account or an organization that's part of an enterprise account. For more information, see "About enterprise accounts."

installation object

The GitHub App installation. Webhook payloads contain the installation property when the event is configured for and sent to a GitHub App. For more information, see "Using webhooks with GitHub Apps."

organization object

A GitHub organization. Webhook payloads contain the organization property when the webhook is configured for an organization, or when the event occurs from activity in a repository owned by an organization.

repository object 必须

The repository on GitHub where the event occurred. Webhook payloads contain the repository property when the event occurs from activity in a repository.

sender object 必须

A GitHub user.

branch_protection_rule

This event occurs when there is activity relating to branch protection rules. For more information, see "About protected branches." For information about the APIs to manage branch protection rules, see the GraphQL documentation or "Branch protection" in the REST API documentation.

To subscribe to this event, a GitHub App must have at least read-level access for the "Administration" repository permission.

branch_protection_rule 的可用性

  • 存储库
  • 组织
  • GitHub应用

branch_protection_rule 的 Webhook 有效负载对象

A branch protection rule was created.

Webhook 请求正文参数
action string 必须

值: created

enterprise object

An enterprise on GitHub. Webhook payloads contain the enterprise property when the webhook is configured on an enterprise account or an organization that's part of an enterprise account. For more information, see "About enterprise accounts."

installation object

The GitHub App installation. Webhook payloads contain the installation property when the event is configured for and sent to a GitHub App. For more information, see "Using webhooks with GitHub Apps."

organization object

A GitHub organization. Webhook payloads contain the organization property when the webhook is configured for an organization, or when the event occurs from activity in a repository owned by an organization.

repository object 必须

The repository on GitHub where the event occurred. Webhook payloads contain the repository property when the event occurs from activity in a repository.

rule object 必须

The branch protection rule. Includes a name and all the branch protection settings applied to branches that match the name. Binary settings are boolean. Multi-level configurations are one of off, non_admins, or everyone. Actor and build lists are arrays of strings.

sender object 必须

A GitHub user.

check_run

This event occurs when there is activity relating to a check run. For information about check runs, see "Getting started with the Checks API." For information about the APIs to manage check runs, see the GraphQL API documentation or "Check Runs" in the REST API documentation.

For activity relating to check suites, use the check-suite event.

To subscribe to this event, a GitHub App must have at least read-level access for the "Checks" repository permission. To receive the rerequested and requested_action event types, the app must have at least write-level access for the "Checks" permission. GitHub Apps with write-level access for the "Checks" permission are automatically subscribed to this webhook event.

Repository and organization webhooks only receive payloads for the created and completed event types in repositories.

The API only looks for pushes in the repository where the check run was created. Pushes to a branch in a forked repository are not detected and return an empty pull_requests array and a null value for head_branch.

check_run 的可用性

  • 存储库
  • 组织
  • GitHub应用

check_run 的 Webhook 有效负载对象

A check run was completed, and a conclusion is available.

Webhook 请求正文参数
action string

值: completed

check_run object 必须

A check performed on the code of a given code change

installation object

The GitHub App installation. Webhook payloads contain the installation property when the event is configured for and sent to a GitHub App. For more information, see "Using webhooks with GitHub Apps."

enterprise object

An enterprise on GitHub. Webhook payloads contain the enterprise property when the webhook is configured on an enterprise account or an organization that's part of an enterprise account. For more information, see "About enterprise accounts."

organization object

A GitHub organization. Webhook payloads contain the organization property when the webhook is configured for an organization, or when the event occurs from activity in a repository owned by an organization.

repository object 必须

The repository on GitHub where the event occurred. Webhook payloads contain the repository property when the event occurs from activity in a repository.

sender object 必须

A GitHub user.

check_suite

This event occurs when there is activity relating to a check suite. For information about check suites, see "Getting started with the Checks API." For information about the APIs to manage check suites, see the GraphQL API documentation or "Check Suites" in the REST API documentation.

For activity relating to check runs, use the check_run event.

To subscribe to this event, a GitHub App must have at least read-level access for the "Checks" permission. To receive the requested and rerequested event types, the app must have at least write-level access for the "Checks" permission. GitHub Apps with write-level access for the "Checks" permission are automatically subscribed to this webhook event.

Repository and organization webhooks only receive payloads for the completed event types in repositories.

The API only looks for pushes in the repository where the check suite was created. Pushes to a branch in a forked repository are not detected and return an empty pull_requests array and a null value for head_branch.

check_suite 的可用性

  • 存储库
  • 组织
  • GitHub应用

check_suite 的 Webhook 有效负载对象

All check runs in a check suite have completed, and a conclusion is available.

Webhook 请求正文参数
action string 必须

值: completed

check_suite object 必须
enterprise object

An enterprise on GitHub. Webhook payloads contain the enterprise property when the webhook is configured on an enterprise account or an organization that's part of an enterprise account. For more information, see "About enterprise accounts."

installation object

The GitHub App installation. Webhook payloads contain the installation property when the event is configured for and sent to a GitHub App. For more information, see "Using webhooks with GitHub Apps."

organization object

A GitHub organization. Webhook payloads contain the organization property when the webhook is configured for an organization, or when the event occurs from activity in a repository owned by an organization.

repository object 必须

The repository on GitHub where the event occurred. Webhook payloads contain the repository property when the event occurs from activity in a repository.

sender object 必须

A GitHub user.

code_scanning_alert

This event occurs when there is activity relating to code scanning alerts in a repository. For more information, see "About code scanning" and "About code scanning alerts." For information about the API to manage code scanning, see "Code scanning" in the REST API documentation.

To subscribe to this event, a GitHub App must have at least read-level access for the "Code scanning alerts" repository permission.

code_scanning_alert 的可用性

  • 存储库
  • 组织
  • GitHub应用

code_scanning_alert 的 Webhook 有效负载对象

A previously created code scanning alert appeared in another branch. This can happen when a branch is merged into or created from a branch with a pre-existing code scanning alert.

Webhook 请求正文参数
action string 必须

值: appeared_in_branch

alert object 必须

The code scanning alert involved in the event.

commit_oid string 必须

The commit SHA of the code scanning alert. When the action is reopened_by_user or closed_by_user, the event was triggered by the sender and this value will be empty.

enterprise object

An enterprise on GitHub. Webhook payloads contain the enterprise property when the webhook is configured on an enterprise account or an organization that's part of an enterprise account. For more information, see "About enterprise accounts."

installation object

The GitHub App installation. Webhook payloads contain the installation property when the event is configured for and sent to a GitHub App. For more information, see "Using webhooks with GitHub Apps."

organization object

A GitHub organization. Webhook payloads contain the organization property when the webhook is configured for an organization, or when the event occurs from activity in a repository owned by an organization.

ref string 必须

The Git reference of the code scanning alert. When the action is reopened_by_user or closed_by_user, the event was triggered by the sender and this value will be empty.

repository object 必须

The repository on GitHub where the event occurred. Webhook payloads contain the repository property when the event occurs from activity in a repository.

sender object 必须

A GitHub user.

commit_comment

This event occurs when there is activity relating to commit comments. For more information about commit comments, see "Commenting on a pull request." For information about the APIs to manage commit comments, see the GraphQL API documentation or "Commit comments" in the REST API documentation.

For activity relating to comments on pull request reviews, use the pull_request_review_comment event. For activity relating to issue comments, use the issue_comment event. For activity relating to discussion comments, use the discussion_comment event.

To subscribe to this event, a GitHub App must have at least read-level access for the "Contents" repository permission.

commit_comment 的可用性

  • 存储库
  • 组织
  • GitHub应用

commit_comment 的 Webhook 有效负载对象

Someone commented on a commit.

Webhook 请求正文参数
action string 必须

The action performed. Can be created.

值: created

comment object 必须

The commit comment resource.

enterprise object

An enterprise on GitHub. Webhook payloads contain the enterprise property when the webhook is configured on an enterprise account or an organization that's part of an enterprise account. For more information, see "About enterprise accounts."

installation object

The GitHub App installation. Webhook payloads contain the installation property when the event is configured for and sent to a GitHub App. For more information, see "Using webhooks with GitHub Apps."

organization object

A GitHub organization. Webhook payloads contain the organization property when the webhook is configured for an organization, or when the event occurs from activity in a repository owned by an organization.

repository object 必须

The repository on GitHub where the event occurred. Webhook payloads contain the repository property when the event occurs from activity in a repository.

sender object 必须

A GitHub user.

create

This event occurs when a Git branch or tag is created.

To subscribe to this event, a GitHub App must have at least read-level access for the "Contents" repository permission.

Notes:

  • This event will not occur when more than three tags are created at once.
  • Payloads are capped at 25 MB. If an event generates a larger payload, GitHub will not deliver a payload for that webhook event. This may happen, for example, if many branches or tags are pushed at once. We suggest monitoring your payload size to ensure delivery.

create 的可用性

  • 存储库
  • 组织
  • GitHub应用

create 的 Webhook 有效负载对象

Webhook 请求正文参数
description string or null 必须

The repository's current description.

enterprise object

An enterprise on GitHub. Webhook payloads contain the enterprise property when the webhook is configured on an enterprise account or an organization that's part of an enterprise account. For more information, see "About enterprise accounts."

installation object

The GitHub App installation. Webhook payloads contain the installation property when the event is configured for and sent to a GitHub App. For more information, see "Using webhooks with GitHub Apps."

master_branch string 必须

The name of the repository's default branch (usually main).

organization object

A GitHub organization. Webhook payloads contain the organization property when the webhook is configured for an organization, or when the event occurs from activity in a repository owned by an organization.

pusher_type string 必须

The pusher type for the event. Can be either user or a deploy key.

ref string 必须

The git ref resource.

ref_type string 必须

The type of Git ref object created in the repository.

可以是以下选项之一: tag, branch

repository object 必须

The repository on GitHub where the event occurred. Webhook payloads contain the repository property when the event occurs from activity in a repository.

sender object 必须

A GitHub user.

custom_property

This event occurs when there is activity relating to a custom property.

For more information, see "Managing custom properties for repositories in your organization". For information about the APIs to manage custom properties, see "Custom properties" in the REST API documentation.

To subscribe to this event, a GitHub App must have at least read-level access for the "Custom properties" organization permission.

custom_property 的可用性

  • 企业
  • 组织
  • GitHub应用

custom_property 的 Webhook 有效负载对象