组织 web 挂钩

关于组织 web 挂钩 API

组织 web 挂钩允许您在组织内发生特定事件时接收 HTTP POST 有效负载。 Web 挂钩 REST API 可让您管理存储库、组织和应用程序 web 挂钩。您还可以使用 REST API 更改 web 挂钩的配置。例如，您可以修改有效负载 URL、内容类型、SSL 验证和机密。更多信息请参阅：

有关您可以订阅的操作的更多信息，请参阅“GitHub 事件类型”。

范围和限制

对组织 web 挂钩的所有操作都需要经过身份验证的用户是所管理组织的管理员。此外，OAuth 令牌需要 admin:org_hook 作用域。更多信息请参阅“OAuth 应用程序的作用域”。

为了保护 web 挂钩配置中可能存在的敏感数据，我们还强制实施以下访问控制规则：

OAuth 应用程序� 法列出、查看或编辑不是它们创建的 web 挂钩。
用户� 法列出、查看或编辑由 OAuth 应用程序创建的 web 挂钩。

接收 web 挂钩

为了让 GitHub Enterprise Server 发送 web 挂钩有效负载，您的服务器需要能够从 Internet 访问。我们还强烈建议使用 SSL，以便我们可以通过 HTTPS 发送� 密的有效负载。

有关更多最佳实践，请参阅我们的指南。

Web 挂钩� �头

GitHub Enterprise Server 发送时将附带� 个 HTTP � �头，以区分事件类型和有效负载� �识符。更多信息请参阅 web 挂钩� �头。

List organization webhooks

使用 GitHub Apps

参数

� �头
名称, 类型, 描述
`accept`string Setting to `application/vnd.github.v3+json` is recommended.
路径参数
名称, 类型, 描述
`org`string必选 The organization name. The name is not case sensitive.
查询参数
名称, 类型, 描述
`per_page`integer The number of results per page (max 100). 默认值: `30`
`page`integer Page number of the results to fetch. 默认值: `1`

HTTP 响应状态代� �

状态代� �	描述
`200`	OK
`404`	Resource not found

代� �示例

get/orgs/{org}/hooks

curl \
  -H "Accept: application/vnd.github.v3+json" \ 
  -H "Authorization: token <TOKEN>" \
  http(s)://HOSTNAME/api/v3/orgs/ORG/hooks

Response

Status: 200

[
  {
    "id": 1,
    "url": "https://api.github.com/orgs/octocat/hooks/1",
    "ping_url": "https://api.github.com/orgs/octocat/hooks/1/pings",
    "name": "web",
    "events": [
      "push",
      "pull_request"
    ],
    "active": true,
    "config": {
      "url": "http://example.com",
      "content_type": "json"
    },
    "updated_at": "2011-09-06T20:39:23Z",
    "created_at": "2011-09-06T17:26:27Z",
    "type": "Organization"
  }
]

Create an organization webhook

使用 GitHub Apps

Here's how you can create a hook that posts payloads in JSON format:

参数

� �头

名称, 类型, 描述

acceptstring

Setting to application/vnd.github.v3+json is recommended.

路径参数

名称, 类型, 描述

orgstring必选

The organization name. The name is not case sensitive.

正文参数

名称, 类型, 描述

namestring必选

Must be passed as "web".

configobject必选

Key/value pairs to provide settings for this webhook. These are defined below.

Properties of theconfigobject

名称, 类型, 描述
`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 `json` and `form`. The default is `form`.
`secret`string If provided, the `secret` will be used as the `key` to generate the HMAC hex digest value for delivery signature headers.
`insecure_ssl`string or number or Determines whether the SSL certificate of the host for `url` will be verified when delivering payloads. Supported values include `0` (verification is performed) and `1` (verification is not performed). The default is `0`. We strongly recommend not setting this to `1` as you are subject to man-in-the-middle and other attacks.
`username`string
`password`string

eventsarray of strings

Determines what events the hook is triggered for.

默认值: push

activeboolean

Determines if notifications are sent when the webhook is triggered. Set to true to send notifications.

默认值: true

HTTP 响应状态代� �

状态代� �	描述
`201`	Created
`404`	Resource not found
`422`	Validation failed

代� �示例

post/orgs/{org}/hooks

curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \ 
  -H "Authorization: token <TOKEN>" \
  http(s)://HOSTNAME/api/v3/orgs/ORG/hooks \
  -d '{"name":"web","active":true,"events":["push","pull_request"],"config":{"url":"http://example.com/webhook","content_type":"json"}}'

Response

Status: 201

{
  "id": 1,
  "url": "https://api.github.com/orgs/octocat/hooks/1",
  "ping_url": "https://api.github.com/orgs/octocat/hooks/1/pings",
  "name": "web",
  "events": [
    "push",
    "pull_request"
  ],
  "active": true,
  "config": {
    "url": "http://example.com",
    "content_type": "json"
  },
  "updated_at": "2011-09-06T20:39:23Z",
  "created_at": "2011-09-06T17:26:27Z",
  "type": "Organization"
}

Get an organization webhook

使用 GitHub Apps

Returns a webhook configured in an organization. To get only the webhook config properties, see "Get a webhook configuration for an organization."

参数

� �头
名称, 类型, 描述
`accept`string Setting to `application/vnd.github.v3+json` is recommended.
路径参数
名称, 类型, 描述
`org`string必选 The organization name. The name is not case sensitive.
`hook_id`integer必选 The unique identifier of the hook.

HTTP 响应状态代� �

状态代� �	描述
`200`	OK
`404`	Resource not found

代� �示例

get/orgs/{org}/hooks/{hook_id}

curl \
  -H "Accept: application/vnd.github.v3+json" \ 
  -H "Authorization: token <TOKEN>" \
  http(s)://HOSTNAME/api/v3/orgs/ORG/hooks/HOOK_ID

Response

Status: 200

{
  "id": 1,
  "url": "https://api.github.com/orgs/octocat/hooks/1",
  "ping_url": "https://api.github.com/orgs/octocat/hooks/1/pings",
  "name": "web",
  "events": [
    "push",
    "pull_request"
  ],
  "active": true,
  "config": {
    "url": "http://example.com",
    "content_type": "json"
  },
  "updated_at": "2011-09-06T20:39:23Z",
  "created_at": "2011-09-06T17:26:27Z",
  "type": "Organization"
}

Update an organization webhook

使用 GitHub Apps

Updates a webhook configured in an organization. When you update a webhook, the secret will be overwritten. 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 an organization."

参数

� �头

名称, 类型, 描述

acceptstring

Setting to application/vnd.github.v3+json is recommended.

路径参数

名称, 类型, 描述

orgstring必选

The organization name. The name is not case sensitive.

hook_idinteger必选

The unique identifier of the hook.

正文参数

名称, 类型, 描述

configobject

Key/value pairs to provide settings for this webhook. These are defined below.

Properties of theconfigobject

名称, 类型, 描述
`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 `json` and `form`. The default is `form`.
`secret`string If provided, the `secret` will be used as the `key` to generate the HMAC hex digest value for delivery signature headers.
`insecure_ssl`string or number or Determines whether the SSL certificate of the host for `url` will be verified when delivering payloads. Supported values include `0` (verification is performed) and `1` (verification is not performed). The default is `0`. We strongly recommend not setting this to `1` as you are subject to man-in-the-middle and other attacks.

eventsarray of strings

Determines what events the hook is triggered for.

默认值: push

activeboolean

Determines if notifications are sent when the webhook is triggered. Set to true to send notifications.

默认值: true

namestring

HTTP 响应状态代� �

状态代� �	描述
`200`	OK
`404`	Resource not found
`422`	Validation failed

代� �示例

patch/orgs/{org}/hooks/{hook_id}

curl \
  -X PATCH \
  -H "Accept: application/vnd.github.v3+json" \ 
  -H "Authorization: token <TOKEN>" \
  http(s)://HOSTNAME/api/v3/orgs/ORG/hooks/HOOK_ID \
  -d '{"active":true,"events":["pull_request"]}'

Response

Status: 200

{
  "id": 1,
  "url": "https://api.github.com/orgs/octocat/hooks/1",
  "ping_url": "https://api.github.com/orgs/octocat/hooks/1/pings",
  "name": "web",
  "events": [
    "pull_request"
  ],
  "active": true,
  "config": {
    "url": "http://example.com",
    "content_type": "json"
  },
  "updated_at": "2011-09-06T20:39:23Z",
  "created_at": "2011-09-06T17:26:27Z",
  "type": "Organization"
}

Delete an organization webhook

使用 GitHub Apps

参数

� �头
名称, 类型, 描述
`accept`string Setting to `application/vnd.github.v3+json` is recommended.
路径参数
名称, 类型, 描述
`org`string必选 The organization name. The name is not case sensitive.
`hook_id`integer必选 The unique identifier of the hook.

HTTP 响应状态代� �

状态代� �	描述
`204`	No Content
`404`	Resource not found

代� �示例

delete/orgs/{org}/hooks/{hook_id}

curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \ 
  -H "Authorization: token <TOKEN>" \
  http(s)://HOSTNAME/api/v3/orgs/ORG/hooks/HOOK_ID

Response

Status: 204

Get a webhook configuration for an organization

使用 GitHub Apps

Returns the webhook configuration for an organization. To get more information about the webhook, including the active state and events, use "Get an organization webhook ."

Access tokens must have the admin:org_hook scope, and GitHub Apps must have the organization_hooks:read permission.

参数

� �头
名称, 类型, 描述
`accept`string Setting to `application/vnd.github.v3+json` is recommended.
路径参数
名称, 类型, 描述
`org`string必选 The organization name. The name is not case sensitive.
`hook_id`integer必选 The unique identifier of the hook.

HTTP 响应状态代� �

状态代� �	描述
`200`	OK

代� �示例

get/orgs/{org}/hooks/{hook_id}/config

curl \
  -H "Accept: application/vnd.github.v3+json" \ 
  -H "Authorization: token <TOKEN>" \
  http(s)://HOSTNAME/api/v3/orgs/ORG/hooks/HOOK_ID/config

Response

Status: 200

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

Update a webhook configuration for an organization

使用 GitHub Apps

Updates the webhook configuration for an organization. To update more information about the webhook, including the active state and events, use "Update an organization webhook ."

Access tokens must have the admin:org_hook scope, and GitHub Apps must have the organization_hooks:write permission.

参数

� �头
名称, 类型, 描述
`accept`string Setting to `application/vnd.github.v3+json` is recommended.
路径参数
名称, 类型, 描述
`org`string必选 The organization name. The name is not case sensitive.
`hook_id`integer必选 The unique identifier of the hook.
正文参数
名称, 类型, 描述
`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 `json` and `form`. The default is `form`.
`secret`string If provided, the `secret` will be used as the `key` to generate the HMAC hex digest value for delivery signature headers.
`insecure_ssl`string or number or Determines whether the SSL certificate of the host for `url` will be verified when delivering payloads. Supported values include `0` (verification is performed) and `1` (verification is not performed). The default is `0`. We strongly recommend not setting this to `1` as you are subject to man-in-the-middle and other attacks.

HTTP 响应状态代� �

状态代� �	描述
`200`	OK

代� �示例

patch/orgs/{org}/hooks/{hook_id}/config

curl \
  -X PATCH \
  -H "Accept: application/vnd.github.v3+json" \ 
  -H "Authorization: token <TOKEN>" \
  http(s)://HOSTNAME/api/v3/orgs/ORG/hooks/HOOK_ID/config \
  -d '{"url":"http://example.com/webhook","content_type":"json","insecure_ssl":"0","secret":"********"}'

Response

Status: 200

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

Ping an organization webhook

使用 GitHub Apps

This will trigger a ping event to be sent to the hook.

参数

� �头
名称, 类型, 描述
`accept`string Setting to `application/vnd.github.v3+json` is recommended.
路径参数
名称, 类型, 描述
`org`string必选 The organization name. The name is not case sensitive.
`hook_id`integer必选 The unique identifier of the hook.

HTTP 响应状态代� �

状态代� �	描述
`204`	No Content
`404`	Resource not found

代� �示例

post/orgs/{org}/hooks/{hook_id}/pings

curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \ 
  -H "Authorization: token <TOKEN>" \
  http(s)://HOSTNAME/api/v3/orgs/ORG/hooks/HOOK_ID/pings

Response

Status: 204