Skip to main content

Organization webhook

Organization webhook API について

Organization の Webhook を使用すると、組織で特定のイベントが発生した場合に必ず HTTP POST ペイロードを受け取ることができます。 Webhook REST API を使用すると、リポジトリ、Organization、アプリ Webhook を管理できます。 この API を使用すると、Webhook の Webhook 配信を一覧表示したり、Webhook の個別の配信を取得して再配信したりできます。Webhook は、外部のアプリまたはサービスに統合できます。 REST API を使用して、Webhook の構成を変更することもできます。 たとえば、ペイロードURL、コンテントタイプ、SSLの検証、シークレットを変更できます。 詳細については、次を参照してください。

サブスクライブできるアクションの詳細については、「GitHub イベントの種類」を参照してください。

スコープと制約事項

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

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

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

webhook の受信

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

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

webhook ヘッダー

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

List organization webhooks

次のもので機能します GitHub Apps

パラメーター

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.

Query parameters
Name, Type, Description
per_pageinteger

The number of results per page (max 100).

Default: 30

pageinteger

Page number of the results to fetch.

Default: 1

HTTP 応答状態コード

status code説明
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.

Name, Type, Description
urlstringRequired

The URL to which the payloads will be delivered.

content_typestring

The media type used to serialize the payloads. Supported values include json and form. The default is form.

secretstring

If provided, the secret will be used as the key to generate the HMAC hex digest value for delivery signature headers.

insecure_sslstring 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.

usernamestring
passwordstring
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 応答状態コード

status code説明
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
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.

HTTP 応答状態コード

status code説明
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.

Name, Type, Description
urlstringRequired

The URL to which the payloads will be delivered.

content_typestring

The media type used to serialize the payloads. Supported values include json and form. The default is form.

secretstring

If provided, the secret will be used as the key to generate the HMAC hex digest value for delivery signature headers.

insecure_sslstring 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 応答状態コード

status code説明
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
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.

HTTP 応答状態コード

status code説明
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
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.

HTTP 応答状態コード

status code説明
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
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
urlstring

The URL to which the payloads will be delivered.

content_typestring

The media type used to serialize the payloads. Supported values include json and form. The default is form.

secretstring

If provided, the secret will be used as the key to generate the HMAC hex digest value for delivery signature headers.

insecure_sslstring 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 応答状態コード

status code説明
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
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.

Query parameters
Name, Type, Description
per_pageinteger

The number of results per page (max 100).

Default: 30

cursorstring

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.

redeliveryboolean

HTTP 応答状態コード

status code説明
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
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.

delivery_idintegerRequired

HTTP 応答状態コード

status code説明
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
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.

delivery_idintegerRequired

HTTP 応答状態コード

status code説明
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

Ping an organization webhook

次のもので機能します GitHub Apps

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

パラメーター

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.

HTTP 応答状態コード

status code説明
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