组织 web 挂钩

关于组织 Webhook API

利用组织 Webhook 可在组织内发生特定事件时接收 HTTP POST 有效负载。使用 Webhook REST API，可以管理存储库、组织和应用 Webhook。可使用此 API 列出 Webhook 的 Webhook 交付，获取并重新交付 Webhook 的个别交付，该交付可以集成到外部应用或服务中。还可使用 REST API 更改 Webhook 的配置。例如，您可以修改有效负载 URL、内容类型、SSL 验证和机密。有关详细信息，请参阅：

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

作用域和限制

对组织 web 挂钩的所有操作都需要经过身份验证的用户是所管理组织的管理员。此外，OAuth 标记需要 admin:org_hook 作用域。有关详细信息，请参阅“OAuth 应用的作用域”。

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

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

接收 web 挂钩

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

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

Web 挂钩标头

GitHub 发送时将附带几个 HTTP 标头，以区分事件类型和有效负载标识符。有关详细信息，请参阅 Webhook标头。

List organization webhooks

使用 GitHub Apps

参数

Headers
Name, Type, Description
`accept`string Setting to `application/vnd.github+json` is recommended.
Path parameters
Name, Type, Description
`org`stringRequired The organization name. The name is not case sensitive.
Query parameters
Name, Type, Description
`per_page`integer The number of results per page (max 100). Default: `30`
`page`integer Page number of the results to fetch. Default: `1`

HTTP 响应状态代码

状态代码	说明
`200`	OK
`404`	Resource not found

代码示例

get/orgs/{org}/hooks

curl \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  https://api.github.com/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",
    "deliveries_url": "https://api.github.com/orgs/octocat/hooks/1/deliveries",
    "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:

参数

Headers

Name, Type, Description

acceptstring

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

Path parameters

Name, Type, Description

orgstringRequired

The organization name. The name is not case sensitive.

Body parameters

Name, Type, Description

namestringRequired

Must be passed as "web".

configobjectRequired

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

Properties of config

Name, Type, Description
`url`stringRequired 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 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. Set to ["*"] to receive all possible events.

Default: ["push"]

activeboolean

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

Default: true

HTTP 响应状态代码

状态代码	说明
`201`	Created
`404`	Resource not found
`422`	Validation failed, or the endpoint has been spammed.

代码示例

post/orgs/{org}/hooks

curl \
  -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  https://api.github.com/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",
  "deliveries_url": "https://api.github.com/orgs/octocat/hooks/1/deliveries",
  "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."

参数

Headers
Name, Type, Description
`accept`string Setting to `application/vnd.github+json` is recommended.
Path parameters
Name, Type, Description
`org`stringRequired The organization name. The name is not case sensitive.
`hook_id`integerRequired 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+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  https://api.github.com/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",
  "deliveries_url": "https://api.github.com/orgs/octocat/hooks/1/deliveries",
  "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."

参数

Headers

Name, Type, Description

acceptstring

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

Path parameters

Name, Type, Description

orgstringRequired

The organization name. The name is not case sensitive.

hook_idintegerRequired

The unique identifier of the hook.

Body parameters

Name, Type, Description

configobject

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

Properties of config

Name, Type, Description
`url`stringRequired 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 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.

Default: ["push"]

activeboolean

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

Default: true

namestring

HTTP 响应状态代码

状态代码	说明
`200`	OK
`404`	Resource not found
`422`	Validation failed, or the endpoint has been spammed.

代码示例

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

curl \
  -X PATCH \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  https://api.github.com/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",
  "deliveries_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/deliveries",
  "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

参数

Headers
Name, Type, Description
`accept`string Setting to `application/vnd.github+json` is recommended.
Path parameters
Name, Type, Description
`org`stringRequired The organization name. The name is not case sensitive.
`hook_id`integerRequired 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+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  https://api.github.com/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.

参数

Headers
Name, Type, Description
`accept`string Setting to `application/vnd.github+json` is recommended.
Path parameters
Name, Type, Description
`org`stringRequired The organization name. The name is not case sensitive.
`hook_id`integerRequired The unique identifier of the hook.

HTTP 响应状态代码

状态代码	说明
`200`	OK

代码示例

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

curl \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  https://api.github.com/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.

参数

Headers
Name, Type, Description
`accept`string Setting to `application/vnd.github+json` is recommended.
Path parameters
Name, Type, Description
`org`stringRequired The organization name. The name is not case sensitive.
`hook_id`integerRequired The unique identifier of the hook.
Body parameters
Name, Type, Description
`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 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+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  https://api.github.com/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"
}

List deliveries for an organization webhook

使用 GitHub Apps

Returns a list of webhook deliveries for a webhook configured in an organization.

参数

Headers
Name, Type, Description
`accept`string Setting to `application/vnd.github+json` is recommended.
Path parameters
Name, Type, Description
`org`stringRequired The organization name. The name is not case sensitive.
`hook_id`integerRequired The unique identifier of the hook.
Query parameters
Name, Type, Description
`per_page`integer The number of results per page (max 100). Default: `30`
`cursor`string Used for pagination: the starting delivery from which the page of deliveries is fetched. Refer to the `link` header for the next and previous page cursors.
`redelivery`boolean

HTTP 响应状态代码

状态代码	说明
`200`	OK
`400`	Bad Request
`422`	Validation failed, or the endpoint has been spammed.

代码示例

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

curl \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  https://api.github.com/orgs/ORG/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
  },
  {
    "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
  }
]

Get a webhook delivery for an organization webhook

使用 GitHub Apps

Returns a delivery for a webhook configured in an organization.

参数

Headers
Name, Type, Description
`accept`string Setting to `application/vnd.github+json` is recommended.
Path parameters
Name, Type, Description
`org`stringRequired The organization name. The name is not case sensitive.
`hook_id`integerRequired The unique identifier of the hook.
`delivery_id`integerRequired

HTTP 响应状态代码

状态代码	说明
`200`	OK
`400`	Bad Request
`422`	Validation failed, or the endpoint has been spammed.

代码示例

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

curl \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  https://api.github.com/orgs/ORG/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",
  "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 an organization webhook

使用 GitHub Apps

Redeliver a delivery for a webhook configured in an organization.

参数

Headers
Name, Type, Description
`accept`string Setting to `application/vnd.github+json` is recommended.
Path parameters
Name, Type, Description
`org`stringRequired The organization name. The name is not case sensitive.
`hook_id`integerRequired The unique identifier of the hook.
`delivery_id`integerRequired

HTTP 响应状态代码

状态代码	说明
`202`	Accepted
`400`	Bad Request
`422`	Validation failed, or the endpoint has been spammed.

代码示例

post/orgs/{org}/hooks/{hook_id}/deliveries/{delivery_id}/attempts

curl \
  -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  https://api.github.com/orgs/ORG/hooks/HOOK_ID/deliveries/DELIVERY_ID/attempts

Accepted

Status: 202

Ping an organization webhook

使用 GitHub Apps

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

参数

Headers
Name, Type, Description
`accept`string Setting to `application/vnd.github+json` is recommended.
Path parameters
Name, Type, Description
`org`stringRequired The organization name. The name is not case sensitive.
`hook_id`integerRequired 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+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  https://api.github.com/orgs/ORG/hooks/HOOK_ID/pings

Response

Status: 204