Organization webhook - GitHub Enterprise Server 3.1 Docs

Organization webhooks APIについて

Organizationのwebhookを使用すると、Organizationで特定のイベントが発生するとき必ずHTTP POST ペイロードを受け取ることができます。 The webhook REST APIs enable you to manage repository, organization, and app webhooks. You can also use the REST API to change the configuration of the webhook. たとえば、ペイロードURL、コンテントタイプ、SSLの検証、シークレットを変更できます。詳しい情� �については、以下を参照してく� さい。

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

スコープと制限

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

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

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

webhook の受信

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

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

webhook ヘッダー

GitHub Enterprise Server は、イベントタイプとペイロード識別子を区別するために、複数の HTTP ヘッダーも送信します。詳細は「webhook ヘッダー」を参照してく� さい。

List organization webhooks

Works with GitHub Apps

パラメータ

Headers
名前, 種類, 説明
`accept`string Setting to `application/vnd.github.v3+json` is recommended.
Path parameters
名前, 種類, 説明
`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 response status codes

Status code	説明
`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

Works with GitHub Apps

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

パラメータ

Headers

名前, 種類, 説明

acceptstring

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

Path parameters

名前, 種類, 説明

orgstring必� �

The organization name. The name is not case sensitive.

Body parameters

名前, 種類, 説明

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 response status codes

Status code	説明
`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

Works with 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
名前, 種類, 説明
`accept`string Setting to `application/vnd.github.v3+json` is recommended.
Path parameters
名前, 種類, 説明
`org`string必� � The organization name. The name is not case sensitive.
`hook_id`integer必� � The unique identifier of the hook.

HTTP response status codes

Status code	説明
`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

Works with 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

名前, 種類, 説明

acceptstring

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

Path parameters

名前, 種類, 説明

orgstring必� �

The organization name. The name is not case sensitive.

hook_idinteger必� �

The unique identifier of the hook.

Body parameters

名前, 種類, 説明

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 response status codes

Status code	説明
`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

Works with GitHub Apps

パラメータ

Headers
名前, 種類, 説明
`accept`string Setting to `application/vnd.github.v3+json` is recommended.
Path parameters
名前, 種類, 説明
`org`string必� � The organization name. The name is not case sensitive.
`hook_id`integer必� � The unique identifier of the hook.

HTTP response status codes

Status code	説明
`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

Works with 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
名前, 種類, 説明
`accept`string Setting to `application/vnd.github.v3+json` is recommended.
Path parameters
名前, 種類, 説明
`org`string必� � The organization name. The name is not case sensitive.
`hook_id`integer必� � The unique identifier of the hook.

HTTP response status codes

Status code	説明
`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

Works with 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
名前, 種類, 説明
`accept`string Setting to `application/vnd.github.v3+json` is recommended.
Path parameters
名前, 種類, 説明
`org`string必� � The organization name. The name is not case sensitive.
`hook_id`integer必� � The unique identifier of the hook.
Body parameters
名前, 種類, 説明
`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 response status codes

Status code	説明
`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

Works with GitHub Apps

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

パラメータ

Headers
名前, 種類, 説明
`accept`string Setting to `application/vnd.github.v3+json` is recommended.
Path parameters
名前, 種類, 説明
`org`string必� � The organization name. The name is not case sensitive.
`hook_id`integer必� � The unique identifier of the hook.

HTTP response status codes

Status code	説明
`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