Organization webhook

REST API を使用して、組織内の Webhook を操作します。

組織の Webhook について

Organization の Webhook を使用すると、組織で特定のイベントが発生した場合に必ず HTTP POST ペイロードを受け取ることができます。詳しくは、「webhook について」を参照してください。

スコープと制約事項

Organization の webhook に対するすべてのアクションでは、認証ユーザが管理対象の Organization の管理者である必要があります。さらに、OAuth トークンには admin:org_hook のスコープが必要です。詳しくは、「OAuth Appのスコープ」を参照してください。

webhook 設定に存在する可能性がある機密データを保護するために、次のアクセス制御ルールも適用します。

OAuth アプリケーションが、それによって作成されたのではない webhook をリスト、表示、編集することはできません。
OAuth アプリケーションによって作成された webhook をユーザがリスト、表示、編集することはできません。

webhook の受信

GitHub AE で webhook ペイロードを送信するには、インターネットからサーバーにアクセスできる必要があります。暗号化されたペイロードを HTTPS 経由で送信できるように、SSL の使用も強く推奨します。

ベストプラクティスについては、ガイドを参照してください。

webhook ヘッダー

GitHub AE は、イベントタイプとペイロード識別子を区別するために、複数の HTTP ヘッダーも送信します。詳細については、Webhook のヘッダーに関する記事を参照してください。

List organization webhooks

に対応 GitHub Apps

"List organization webhooks" のパラメーター

ヘッダー
名前, Type, 説明
`accept` string Setting to `application/vnd.github+json` is recommended.
パスパラメーター
名前, Type, 説明
`org` string 必須 The organization name. The name is not case sensitive.
クエリパラメーター
名前, Type, 説明
`per_page` integer The number of results per page (max 100). Default: `30`
`page` integer Page number of the results to fetch. Default: `1`

"List organization webhooks" の HTTP 応答状態コード

状態コード	説明
`200`	OK
`404`	Resource not found

"List organization webhooks" のコードサンプル

get/orgs/{org}/hooks

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

"Create an organization webhook" のパラメーター

ヘッダー

名前, Type, 説明

accept string

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

パスパラメーター

名前, Type, 説明

org string 必須

The organization name. The name is not case sensitive.

本文のパラメーター

名前, Type, 説明

name string 必須

Must be passed as "web".

config object 必須

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

Properties of config

名前, Type, 説明
`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.
`username` string
`password` string

events array of strings

Determines what events the hook is triggered for. Set to ["*"] to receive all possible events.

Default: ["push"]

active boolean

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

Default: true

"Create an organization webhook" の HTTP 応答状態コード

状態コード	説明
`201`	Created
`404`	Resource not found
`422`	Validation failed, or the endpoint has been spammed.

"Create an organization webhook" のコードサンプル

post/orgs/{org}/hooks

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

"Get an organization webhook" のパラメーター

ヘッダー
名前, Type, 説明
`accept` string Setting to `application/vnd.github+json` is recommended.
パスパラメーター
名前, Type, 説明
`org` string 必須 The organization name. The name is not case sensitive.
`hook_id` integer 必須 The unique identifier of the hook.

"Get an organization webhook" の HTTP 応答状態コード

状態コード	説明
`200`	OK
`404`	Resource not found

"Get an organization webhook" のコードサンプル

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

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

"Update an organization webhook" のパラメーター

ヘッダー

名前, Type, 説明

accept string

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

パスパラメーター

名前, Type, 説明

org string 必須

The organization name. The name is not case sensitive.

hook_id integer 必須

The unique identifier of the hook.

本文のパラメーター

名前, Type, 説明

config object

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

Properties of config

名前, Type, 説明
`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.

events array of strings

Determines what events the hook is triggered for.

Default: ["push"]

active boolean

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

Default: true

name string

"Update an organization webhook" の HTTP 応答状態コード

状態コード	説明
`200`	OK
`404`	Resource not found
`422`	Validation failed, or the endpoint has been spammed.

"Update an organization webhook" のコードサンプル

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

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

"Delete an organization webhook" のパラメーター

ヘッダー
名前, Type, 説明
`accept` string Setting to `application/vnd.github+json` is recommended.
パスパラメーター
名前, Type, 説明
`org` string 必須 The organization name. The name is not case sensitive.
`hook_id` integer 必須 The unique identifier of the hook.

"Delete an organization webhook" の HTTP 応答状態コード

状態コード	説明
`204`	No Content
`404`	Resource not found

"Delete an organization webhook" のコードサンプル

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

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

"Get a webhook configuration for an organization" のパラメーター

ヘッダー
名前, Type, 説明
`accept` string Setting to `application/vnd.github+json` is recommended.
パスパラメーター
名前, Type, 説明
`org` string 必須 The organization name. The name is not case sensitive.
`hook_id` integer 必須 The unique identifier of the hook.

"Get a webhook configuration for an organization" の HTTP 応答状態コード

状態コード	説明
`200`	OK

"Get a webhook configuration for an organization" のコードサンプル

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

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

"Update a webhook configuration for an organization" のパラメーター

ヘッダー
名前, Type, 説明
`accept` string Setting to `application/vnd.github+json` is recommended.
パスパラメーター
名前, Type, 説明
`org` string 必須 The organization name. The name is not case sensitive.
`hook_id` integer 必須 The unique identifier of the hook.
本文のパラメーター
名前, Type, 説明
`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.

"Update a webhook configuration for an organization" の HTTP 応答状態コード

状態コード	説明
`200`	OK

"Update a webhook configuration for an organization" のコードサンプル

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

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

List deliveries for an organization webhook

に対応 GitHub Apps

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

"List deliveries for an organization webhook" のパラメーター

ヘッダー
名前, Type, 説明
`accept` string Setting to `application/vnd.github+json` is recommended.
パスパラメーター
名前, Type, 説明
`org` string 必須 The organization name. The name is not case sensitive.
`hook_id` integer 必須 The unique identifier of the hook.
クエリパラメーター
名前, Type, 説明
`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

"List deliveries for an organization webhook" の HTTP 応答状態コード

状態コード	説明
`200`	OK
`400`	Bad Request
`422`	Validation failed, or the endpoint has been spammed.

"List deliveries for an organization webhook" のコードサンプル

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

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

"Get a webhook delivery for an organization webhook" のパラメーター

ヘッダー
名前, Type, 説明
`accept` string Setting to `application/vnd.github+json` is recommended.
パスパラメーター
名前, Type, 説明
`org` string 必須 The organization name. The name is not case sensitive.
`hook_id` integer 必須 The unique identifier of the hook.
`delivery_id` integer 必須

"Get a webhook delivery for an organization webhook" の HTTP 応答状態コード

状態コード	説明
`200`	OK
`400`	Bad Request
`422`	Validation failed, or the endpoint has been spammed.

"Get a webhook delivery for an organization webhook" のコードサンプル

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

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

"Redeliver a delivery for an organization webhook" のパラメーター

ヘッダー
名前, Type, 説明
`accept` string Setting to `application/vnd.github+json` is recommended.
パスパラメーター
名前, Type, 説明
`org` string 必須 The organization name. The name is not case sensitive.
`hook_id` integer 必須 The unique identifier of the hook.
`delivery_id` integer 必須

"Redeliver a delivery for an organization webhook" の HTTP 応答状態コード

状態コード	説明
`202`	Accepted
`400`	Bad Request
`422`	Validation failed, or the endpoint has been spammed.

"Redeliver a delivery for an organization webhook" のコードサンプル

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

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

"Ping an organization webhook" のパラメーター

ヘッダー
名前, Type, 説明
`accept` string Setting to `application/vnd.github+json` is recommended.
パスパラメーター
名前, Type, 説明
`org` string 必須 The organization name. The name is not case sensitive.
`hook_id` integer 必須 The unique identifier of the hook.

"Ping an organization webhook" の HTTP 応答状態コード

状態コード	説明
`204`	No Content
`404`	Resource not found

"Ping an organization webhook" のコードサンプル

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

curl -L \
  -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  https://HOSTNAME/api/v3/orgs/ORG/hooks/HOOK_ID/pings

Response

Status: 204