创建 web 挂钩

可以创建 Webhook 来订阅在 GitHub 上发生的特定事件。

本文内容

关于创建 Webhook

可以通过创建 Webhook 订阅存储库、组织、GitHub Enterprise、 或 GitHub App 中发生的 GitHub 中的特定事件。

有关不同类型的 Webhook 的详细信息，请参阅“Webhook 的类型”。

有关 Webhook 事件的完整列表，请参阅“Webhook 事件和有效负载”。

创建存储库 Webhook

可以创建 Webhook 以订阅在特定存储库中发生的事件。 必须是存储库所有者，或在存储库中具有管理员访问权限的人员，才能在该存储库中创建 Webhook。

可以使用 GitHub Web 界面或 REST API 来创建存储库 Webhook。 有关使用 REST API 创建存储库 Webhook 的详细信息，请参阅“存储库 Webhook 的 REST API 终结点”。

  1. 在 GitHub 上，导航到存储库的主页面。

  2. 在存储库名称下，单击 “设置”。 如果看不到“设置”选项卡，请选择“”下拉菜单，然后单击“设置”。

    存储库标头的屏幕截图，其中显示了选项卡。 “设置”选项卡以深橙色边框突出显示。

  3. 在左侧边栏中，单击 “Webhook”。

  4. 单击“添加 Webhook” 。

  5. 在“有效负载 URL”下，键入要接收有效负载的 URL。

  6. （可选）选择“内容类型”下拉菜单，然后单击一种数据格式以接收 Webhook 有效负载。

    • application/json 直接将 JSON 有效负载作为 POST POST 请求的正文传递。
    • application/x-www-form-urlencoded 将 JSON 有效负载作为表单参数发送，称为 payload。

  7. （可选）在“机密”下，键入用作 secret 密钥的字符串。 应选择高熵的随机文本字符串。 可以使用 Webhook 机密，将传入请求限制为仅源自 GitHub 的请求。 有关详细信息，请参阅“验证 Webhook 交付”。

  8. 在“你希望通过哪些事件来触发此 Webhook？”下，选择要接收的 Webhook 事件。 应仅订阅需要的 Webhook 事件。

  9. 如果选择****“让我选择单个事件”，请选择你希望触发 Webhook 的事件。

  10. 要在添加配置后使 Webhook 处于活动状态，请选择“活动”。

  11. 单击“添加 Webhook” 。

创建新的 Webhook 后，GitHub 将向你发送一个简单的 ping 事件，告知你已正确设置 Webhook。 有关详细信息，请参阅“Webhook 事件和有效负载”。

创建组织 Webhook

可以创建 Webhook 以订阅在特定组织中发生的事件。 必须是组织所有者，才可以在该组织中创建 Webhook。

可以使用 GitHub Web 界面或 REST API 来创建组织 Webhook。 有关使用 REST API 创建组织 Webhook 的详细信息，请参阅“适用于组织 Webhook 的 REST API 终结点”。

  1. 在 GitHub 上任意页的右上角，单击你的个人资料照片。
  2. 单击“你的组织”。
  3. 在组织右侧，单击“设置”。
  4. 在左侧边栏中，单击 “Webhook”。
  5. 单击“添加 Webhook” 。
  6. 在“有效负载 URL”下，键入要接收有效负载的 URL。
  7. （可选）选择“内容类型”下拉菜单，然后单击一种数据格式以接收 Webhook 有效负载。
    • application/json 直接将 JSON 有效负载作为 POST POST 请求的正文传递。
    • application/x-www-form-urlencoded 将 JSON 有效负载作为表单参数发送，称为 payload。
  8. （可选）在“机密”下，键入用作 secret 密钥的字符串。 应选择高熵的随机文本字符串。 可以使用 Webhook 机密，将传入请求限制为仅源自 GitHub 的请求。 有关详细信息，请参阅“验证 Webhook 交付”。
  9. 在“你希望通过哪些事件来触发此 Webhook？”下，选择要接收的 Webhook 类型。 应仅订阅需要的 Webhook 事件。
  10. 如果选择“让我选择单个事件”****，请选择将会触发 Webhook 的事件。
  11. 要在添加配置后使 Webhook 处于活动状态，请选择“活动”。
  12. 单击“添加 Webhook” 。

创建新的 Webhook 后，GitHub 将向你发送一个简单的 ping 事件，告知你已正确设置 Webhook。 有关详细信息，请参阅“Webhook 事件和有效负载”。

为 GitHub Enterprise

创建全局 Webhook

企业所有者可以创建全局 Webhook 以订阅在企业中发生的事件。

可以使用 GitHub Web 界面或 REST API 来创建全局 Webhook。 有关使用 REST API 创建全局 Webhook 的详细信息，请参阅“适用于全局 Webhook 的 REST API 终结点”。

  1. 在 GitHub Enterprise Server 的右上角，单击你的个人资料照片，然后单击“企业设置”****。

    单击 GitHub Enterprise Server 上的个人资料照片时显示的下拉菜单的屏幕截图。 “企业设置”选项以深橙色边框突出显示。

  2. 在页面左侧的企业帐户边栏中，单击 “设置”。

  3. 在“ 设置”下，单击“挂钩”。

  4. 单击“添加 Webhook” 。

  5. 在“有效负载 URL”字段中，键入要接收有效负载的 URL。

  6. （可选）选择“内容类型”下拉菜单，然后单击一种数据格式以接收 Webhook 有效负载。

    • application/json 直接将 JSON 有效负载作为 POST POST 请求的正文传递。
    • application/x-www-form-urlencoded 将 JSON 有效负载作为表单参数发送，称为 payload。

  7. （可选）在“机密”下，键入用作 secret 密钥的字符串。 应选择高熵的随机文本字符串。 可以使用 Webhook 机密，将传入请求限制为仅源自 GitHub 的请求。 有关详细信息，请参阅“验证 Webhook 交付”。

  8. （可选）如果有效负载 URL 为 HTTPS，并且你不希望 GitHub Enterprise Server 在传递有效负载时验证 SSL 证书，请选择“禁用”。 阅读有关 SSL 验证的信息，然后单击“禁用，我已了解我的 Webhook 可能不安全”。

    Warning

    SSL 验证有助于确保安全传递挂钩有效负载。 我们不建议禁用 SSL 验证。

  9. 在“你希望通过哪些事件来触发此 Webhook？”下，选择要接收的 Webhook 类型。 应仅订阅需要的 Webhook 事件。

  10. 如果选择“让我选择单个事件”****，请选择将会触发 Webhook 的事件。

  11. 要在添加配置后使 Webhook 处于活动状态，请选择“活动”。

  12. 单击“添加 Webhook” 。

为 GitHub App 创建 Webhook。

GitHub App 的所有者可以为应用订阅 Webhook 事件，以便在发生特定事件时收到通知。 如果组织已为其拥有的 GitHub App 指定了任何应用管理员，应用管理员也可以为应用订阅 Webhook 事件。 有关详细信息，请参阅“将 Webhook 与 GitHub 应用配合使用”。

每个 GitHub App 有一个 Webhook。 可以在注册 GitHub App 时配置 Webhook，也可以编辑现有 GitHub App 注册的 Webhook 配置。

有关注册 GitHub App 时配置 Webhook 的详细信息，请参阅“注册 GitHub 应用”。

要为现有 GitHub App 注册配置 Webhook：

  1. 在 GitHub 上任意页的右上角，单击你的个人资料照片。

  2. 导航到你的帐户设置。

    • 对于由个人帐户拥有的应用，请单击“设置”****。
    • 对于组织拥有的应用：
      1. 单击“你的组织”。
      2. 在组织的右侧，单击设置。

  3. 在左侧边栏中，单击“ 开发人员设置”。

  4. 在左侧边栏中，单击“GitHub Apps”。

  5. 在要为其配置 Webhook 的 GitHub App 旁边，单击“编辑”****。

  6. 在“Webhook”下，选择“活动”****。

  7. 在“Webhook URL”下，键入要接收有效负载的 URL。

  8. （可选）在“Webhook 机密”下，键入用作 secret 密钥的字符串。 应选择高熵的随机文本字符串。 可以使用 Webhook 机密，将传入请求限制为仅源自 GitHub 的请求。 有关详细信息，请参阅“验证 Webhook 交付”。

  9. 单击“保存更改”。

  10. 在边栏中，单击“权限和事件”****。

  11. 可以为 GitHub App 注册选择的具体 Webhook 事件根据为应用选择的权限类型而定。 首先需要选择希望应用拥有的权限，然后可以让应用订阅与该权限集相关的 Webhook 事件。

    在“存储库权限”、“组织权限”和“帐户权限”部分下，选择应用将订阅的事件所需的权限。 有关详细信息，请参阅“为 GitHub Apps 选择权限”。 有关更改权限时需考虑事项的详细信息，请参阅修改 GitHub App 注册。

  12. 在“订阅事件”下，选择希望 GitHub App 接收的 Webhook 事件。

  13. 单击“保存更改”。

可以使用 REST API 为 GitHub App 创建 Webhook。 有关详细信息，请参阅“GitHub App Webhook 的 REST API 终结点”。

其他阅读材料