このバージョンの GitHub Enterprise はこの日付をもって終了となりました: 2023-01-18. 重大なセキュリティの問題に対してであっても、パッチリリースは作成されません。 パフォーマンスの向上、セキュリティの向上、新機能の向上を図るために、最新バージョンの GitHub Enterprise にアップグレードします。 アップグレードに関するヘルプについては、GitHub Enterprise サポートにお問い合わせく� さい。
Organization webhook
Organization webhook API について
Organization の Webhook を使用すると、組織で特定のイベントが発生した� �合に必ず HTTP POST
ペイロードを受け取ることができます。 REST API を利用し、リポジトリ、組織、アプリ Webhook を管理できます。 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 Server で webhook ペイロードを送信するには、インターネットからサーバーにアクセスできる必要があります。 暗号化されたペイロードを HTTPS 経由で送信できるように、SSL の使用も強く推奨します。
ベスト プラクティスについては、ガイドを参照してく� さい。
webhook ヘッダー
GitHub Enterprise Server は、イベントタイプとペイロード識別子を区別するために、複数の HTTP ヘッダーも送信します。 詳細については、Webhook のヘッダーに関する記事を参照してく� さい。
List organization webhooks
パラメーター
Headers |
---|
Name, Type, Description |
accept stringSetting to |
Path parameters |
Name, Type, Description |
org stringRequiredThe organization name. The name is not case sensitive. |
Query parameters |
Name, Type, Description |
per_page integerThe number of results per page (max 100). Default: |
page integerPage number of the results to fetch. Default: |
HTTP 応答状態コード
status code | 説明 |
---|---|
200 | OK |
404 | Resource not found |
コード サンプル
curl \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-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",
"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
Here's how you can create a hook that posts payloads in JSON format:
パラメーター
Headers | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
Name, Type, Description | ||||||||||
accept stringSetting to | ||||||||||
Path parameters | ||||||||||
Name, Type, Description | ||||||||||
org stringRequiredThe organization name. The name is not case sensitive. | ||||||||||
Body parameters | ||||||||||
Name, Type, Description | ||||||||||
name stringRequiredMust be passed as "web". | ||||||||||
config objectRequiredKey/value pairs to provide settings for this webhook. These are defined below. | ||||||||||
Properties of |
Name, Type, Description |
---|
url stringRequiredThe URL to which the payloads will be delivered. |
content_type stringThe media type used to serialize the payloads. Supported values include |
secret stringIf provided, the |
insecure_ssl string or numberDetermines whether the SSL certificate of the host for |
username string |
password string |
events
array of stringsDetermines what events the hook is triggered for. Set to ["*"]
to receive all possible events.
Default: ["push"]
active
booleanDetermines 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. |
コード サンプル
curl \
-X POST \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-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",
"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
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 stringSetting to |
Path parameters |
Name, Type, Description |
org stringRequiredThe organization name. The name is not case sensitive. |
hook_id integerRequiredThe unique identifier of the hook. |
HTTP 応答状態コード
status code | 説明 |
---|---|
200 | OK |
404 | Resource not found |
コード サンプル
curl \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-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",
"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
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 | ||||||||
accept stringSetting to | ||||||||
Path parameters | ||||||||
Name, Type, Description | ||||||||
org stringRequiredThe organization name. The name is not case sensitive. | ||||||||
hook_id integerRequiredThe unique identifier of the hook. | ||||||||
Body parameters | ||||||||
Name, Type, Description | ||||||||
config objectKey/value pairs to provide settings for this webhook. These are defined below. | ||||||||
Properties of |
Name, Type, Description |
---|
url stringRequiredThe URL to which the payloads will be delivered. |
content_type stringThe media type used to serialize the payloads. Supported values include |
secret stringIf provided, the |
insecure_ssl string or numberDetermines whether the SSL certificate of the host for |
events
array of stringsDetermines what events the hook is triggered for.
Default: ["push"]
active
booleanDetermines if notifications are sent when the webhook is triggered. Set to true
to send notifications.
Default: true
name
stringHTTP 応答状態コード
status code | 説明 |
---|---|
200 | OK |
404 | Resource not found |
422 | Validation failed, or the endpoint has been spammed. |
コード サンプル
curl \
-X PATCH \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-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",
"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
パラメーター
Headers |
---|
Name, Type, Description |
accept stringSetting to |
Path parameters |
Name, Type, Description |
org stringRequiredThe organization name. The name is not case sensitive. |
hook_id integerRequiredThe unique identifier of the hook. |
HTTP 応答状態コード
status code | 説明 |
---|---|
204 | No Content |
404 | Resource not found |
コード サンプル
curl \
-X DELETE \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
http(s)://HOSTNAME/api/v3/orgs/ORG/hooks/HOOK_ID
Response
Status: 204
Get a webhook configuration for an organization
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 stringSetting to |
Path parameters |
Name, Type, Description |
org stringRequiredThe organization name. The name is not case sensitive. |
hook_id integerRequiredThe unique identifier of the hook. |
HTTP 応答状態コード
status code | 説明 |
---|---|
200 | OK |
コード サンプル
curl \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-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
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 stringSetting to |
Path parameters |
Name, Type, Description |
org stringRequiredThe organization name. The name is not case sensitive. |
hook_id integerRequiredThe unique identifier of the hook. |
Body parameters |
Name, Type, Description |
url stringThe URL to which the payloads will be delivered. |
content_type stringThe media type used to serialize the payloads. Supported values include |
secret stringIf provided, the |
insecure_ssl string or numberDetermines whether the SSL certificate of the host for |
HTTP 応答状態コード
status code | 説明 |
---|---|
200 | OK |
コード サンプル
curl \
-X PATCH \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-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"
}
List deliveries for an organization webhook
Returns a list of webhook deliveries for a webhook configured in an organization.
パラメーター
Headers |
---|
Name, Type, Description |
accept stringSetting to |
Path parameters |
Name, Type, Description |
org stringRequiredThe organization name. The name is not case sensitive. |
hook_id integerRequiredThe unique identifier of the hook. |
Query parameters |
Name, Type, Description |
per_page integerThe number of results per page (max 100). Default: |
cursor stringUsed for pagination: the starting delivery from which the page of deliveries is fetched. Refer to the |
redelivery boolean |
HTTP 応答状態コード
status code | 説明 |
---|---|
200 | OK |
400 | Bad Request |
422 | Validation failed, or the endpoint has been spammed. |
コード サンプル
curl \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
http(s)://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
Returns a delivery for a webhook configured in an organization.
パラメーター
Headers |
---|
Name, Type, Description |
accept stringSetting to |
Path parameters |
Name, Type, Description |
org stringRequiredThe organization name. The name is not case sensitive. |
hook_id integerRequiredThe unique identifier of the hook. |
delivery_id integerRequired |
HTTP 応答状態コード
status code | 説明 |
---|---|
200 | OK |
400 | Bad Request |
422 | Validation failed, or the endpoint has been spammed. |
コード サンプル
curl \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
http(s)://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",
"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
Redeliver a delivery for a webhook configured in an organization.
パラメーター
Headers |
---|
Name, Type, Description |
accept stringSetting to |
Path parameters |
Name, Type, Description |
org stringRequiredThe organization name. The name is not case sensitive. |
hook_id integerRequiredThe unique identifier of the hook. |
delivery_id integerRequired |
HTTP 応答状態コード
status code | 説明 |
---|---|
202 | Accepted |
400 | Bad Request |
422 | Validation failed, or the endpoint has been spammed. |
コード サンプル
curl \
-X POST \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
http(s)://HOSTNAME/api/v3/orgs/ORG/hooks/HOOK_ID/deliveries/DELIVERY_ID/attempts
Accepted
Status: 202
Ping an organization webhook
This will trigger a ping event to be sent to the hook.
パラメーター
Headers |
---|
Name, Type, Description |
accept stringSetting to |
Path parameters |
Name, Type, Description |
org stringRequiredThe organization name. The name is not case sensitive. |
hook_id integerRequiredThe unique identifier of the hook. |
HTTP 応答状態コード
status code | 説明 |
---|---|
204 | No Content |
404 | Resource not found |
コード サンプル
curl \
-X POST \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
http(s)://HOSTNAME/api/v3/orgs/ORG/hooks/HOOK_ID/pings
Response
Status: 204