Repository webhooks allow you to receive HTTP POST
payloads whenever certain events happen in a repository. 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の検証、シークレットを変更できます。 詳しい情� �については、以下を参照してく� さい。
Organization のすべてのリポジトリからイベントを受信するため単一の webhook を設定する� �合は、Organization Webhooks の API ドキュメントを参照してく� さい。
In addition to the REST API, GitHub can also serve as a PubSubHubbub hub for repositories.
リポジトリ webhook
get /repos/{owner}/{repo}/hooks
パラメータ
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
owner |
string | path | |
repo |
string | path | |
per_page |
integer | query |
Results per page (max 100) Default:30 |
page |
integer | query |
Page number of the results to fetch. Default:1 |
コードサンプル
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/repos/octocat/hello-world/hooks
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/hooks', {
owner: 'octocat',
repo: 'hello-world'
})
Response
Status: 200 OK
[
{
"type": "Repository",
"id": 12345678,
"name": "web",
"active": true,
"events": [
"push",
"pull_request"
],
"config": {
"content_type": "json",
"insecure_ssl": "0",
"url": "https://example.com/webhook"
},
"updated_at": "2019-06-03T00:57:16Z",
"created_at": "2019-06-03T00:57:16Z",
"url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678",
"test_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/test",
"ping_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/pings",
"last_response": {
"code": null,
"status": "unused",
"message": null
}
}
]
Resource not found
Status: 404 Not Found
Notes
Create a repository webhook
Repositories can have multiple webhooks installed. Each webhook should have a unique config
. Multiple webhooks can
share the same config
as long as those webhooks do not have any events
that overlap.
post /repos/{owner}/{repo}/hooks
パラメータ
Name | Type | In | Description | ||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
accept |
string | header |
Setting to
|
||||||||||||||
owner |
string | path | |||||||||||||||
repo |
string | path | |||||||||||||||
name |
string | body |
Use |
||||||||||||||
config |
object | body |
Key/value pairs to provide settings for this webhook. These are defined below. |
||||||||||||||
Properties of the
|
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 |
secret (string)
|
If provided, the |
insecure_ssl (string or number)
|
Determines whether the SSL certificate of the host for |
token (string)
|
|
digest (string)
|
events
Determines what events the hook is triggered for.
Default:push
active
Determines if notifications are sent when the webhook is triggered. Set to true
to send notifications.
true
コードサンプル
Shell
curl \
-X POST \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/repos/octocat/hello-world/hooks \
-d '{"name":"name"}'
JavaScript (@octokit/core.js)
await octokit.request('POST /repos/{owner}/{repo}/hooks', {
owner: 'octocat',
repo: 'hello-world',
name: 'name'
})
Response
Status: 201 Created
{
"type": "Repository",
"id": 12345678,
"name": "web",
"active": true,
"events": [
"push",
"pull_request"
],
"config": {
"content_type": "json",
"insecure_ssl": "0",
"url": "https://example.com/webhook"
},
"updated_at": "2019-06-03T00:57:16Z",
"created_at": "2019-06-03T00:57:16Z",
"url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678",
"test_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/test",
"ping_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/pings",
"last_response": {
"code": null,
"status": "unused",
"message": null
}
}
Forbidden
Status: 403 Forbidden
Resource not found
Status: 404 Not Found
Validation failed
Status: 422 Unprocessable Entity
Notes
Get a repository webhook
Returns a webhook configured in a repository. To get only the webhook config
properties, see "Get a webhook configuration for a repository."
get /repos/{owner}/{repo}/hooks/{hook_id}
パラメータ
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
owner |
string | path | |
repo |
string | path | |
hook_id |
integer | path |
コードサンプル
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/repos/octocat/hello-world/hooks/42
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/hooks/{hook_id}', {
owner: 'octocat',
repo: 'hello-world',
hook_id: 42
})
Response
Status: 200 OK
{
"type": "Repository",
"id": 12345678,
"name": "web",
"active": true,
"events": [
"push",
"pull_request"
],
"config": {
"content_type": "json",
"insecure_ssl": "0",
"url": "https://example.com/webhook"
},
"updated_at": "2019-06-03T00:57:16Z",
"created_at": "2019-06-03T00:57:16Z",
"url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678",
"test_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/test",
"ping_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/pings",
"last_response": {
"code": null,
"status": "unused",
"message": null
}
}
Resource not found
Status: 404 Not Found
Notes
Update a repository webhook
Updates a webhook configured in a repository. 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 a repository."
patch /repos/{owner}/{repo}/hooks/{hook_id}
パラメータ
Name | Type | In | Description | ||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
accept |
string | header |
Setting to
|
||||||||||||||
owner |
string | path | |||||||||||||||
repo |
string | path | |||||||||||||||
hook_id |
integer | path | |||||||||||||||
config |
object | body |
Key/value pairs to provide settings for this webhook. These are defined below. |
||||||||||||||
Properties of the
|
Name (Type) | Description |
---|---|
url (string)
|
Required. The URL to which the payloads will be delivered. |
content_type (string)
|
The media type used to serialize the payloads. Supported values include |
secret (string)
|
If provided, the |
insecure_ssl (string or number)
|
Determines whether the SSL certificate of the host for |
address (string)
|
|
room (string)
|
events
Determines what events the hook is triggered for. This replaces the entire array of events.
Default:push
add_events
Determines a list of events to be added to the list of events that the Hook triggers for.
remove_events
Determines a list of events to be removed from the list of events that the Hook triggers for.
active
Determines if notifications are sent when the webhook is triggered. Set to true
to send notifications.
true
コードサンプル
Shell
curl \
-X PATCH \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/repos/octocat/hello-world/hooks/42 \
-d '{"config":{"url":"url","content_type":"content_type","secret":"secret","insecure_ssl":"insecure_ssl","address":"address","room":"room"}}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /repos/{owner}/{repo}/hooks/{hook_id}', {
owner: 'octocat',
repo: 'hello-world',
hook_id: 42,
config: {
url: 'url',
content_type: 'content_type',
secret: 'secret',
insecure_ssl: 'insecure_ssl',
address: 'address',
room: 'room'
}
})
Response
Status: 200 OK
{
"type": "Repository",
"id": 12345678,
"name": "web",
"active": true,
"events": [
"push",
"pull_request"
],
"config": {
"content_type": "json",
"insecure_ssl": "0",
"url": "https://example.com/webhook"
},
"updated_at": "2019-06-03T00:57:16Z",
"created_at": "2019-06-03T00:57:16Z",
"url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678",
"test_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/test",
"ping_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/pings",
"last_response": {
"code": null,
"status": "unused",
"message": null
}
}
Resource not found
Status: 404 Not Found
Validation failed
Status: 422 Unprocessable Entity
Notes
delete /repos/{owner}/{repo}/hooks/{hook_id}
パラメータ
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
owner |
string | path | |
repo |
string | path | |
hook_id |
integer | path |
コードサンプル
Shell
curl \
-X DELETE \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/repos/octocat/hello-world/hooks/42
JavaScript (@octokit/core.js)
await octokit.request('DELETE /repos/{owner}/{repo}/hooks/{hook_id}', {
owner: 'octocat',
repo: 'hello-world',
hook_id: 42
})
Response
Status: 204 No Content
Resource not found
Status: 404 Not Found
Notes
Ping a repository webhook
This will trigger a ping event to be sent to the hook.
post /repos/{owner}/{repo}/hooks/{hook_id}/pings
パラメータ
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
owner |
string | path | |
repo |
string | path | |
hook_id |
integer | path |
コードサンプル
Shell
curl \
-X POST \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/repos/octocat/hello-world/hooks/42/pings
JavaScript (@octokit/core.js)
await octokit.request('POST /repos/{owner}/{repo}/hooks/{hook_id}/pings', {
owner: 'octocat',
repo: 'hello-world',
hook_id: 42
})
Response
Status: 204 No Content
Resource not found
Status: 404 Not Found
Notes
Test the push repository webhook
This will trigger the hook with the latest push to the current repository if the hook is subscribed to push
events. If the hook is not subscribed to push
events, the server will respond with 204 but no test POST will be generated.
Note: Previously /repos/:owner/:repo/hooks/:hook_id/test
post /repos/{owner}/{repo}/hooks/{hook_id}/tests
パラメータ
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
owner |
string | path | |
repo |
string | path | |
hook_id |
integer | path |
コードサンプル
Shell
curl \
-X POST \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/repos/octocat/hello-world/hooks/42/tests
JavaScript (@octokit/core.js)
await octokit.request('POST /repos/{owner}/{repo}/hooks/{hook_id}/tests', {
owner: 'octocat',
repo: 'hello-world',
hook_id: 42
})
Response
Status: 204 No Content
Resource not found
Status: 404 Not Found
Notes
Repository webhook configuration
Get a webhook configuration for a repository
Returns the webhook configuration for a repository. To get more information about the webhook, including the active
state and events
, use "Get a repository webhook."
Access tokens must have the read:repo_hook
or repo
scope, and GitHub Apps must have the repository_hooks:read
permission.
get /repos/{owner}/{repo}/hooks/{hook_id}/config
パラメータ
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
owner |
string | path | |
repo |
string | path | |
hook_id |
integer | path |
コードサンプル
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/repos/octocat/hello-world/hooks/42/config
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/hooks/{hook_id}/config', {
owner: 'octocat',
repo: 'hello-world',
hook_id: 42
})
Response
Status: 200 OK
{
"content_type": "json",
"insecure_ssl": "0",
"secret": "********",
"url": "https://example.com/webhook"
}
Notes
Update a webhook configuration for a repository
Updates the webhook configuration for a repository. To update more information about the webhook, including the active
state and events
, use "Update a repository webhook."
Access tokens must have the write:repo_hook
or repo
scope, and GitHub Apps must have the repository_hooks:write
permission.
patch /repos/{owner}/{repo}/hooks/{hook_id}/config
パラメータ
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
owner |
string | path | |
repo |
string | path | |
hook_id |
integer | path | |
url |
string | body |
The URL to which the payloads will be delivered. |
content_type |
string | body |
The media type used to serialize the payloads. Supported values include |
secret |
string | body |
If provided, the |
insecure_ssl |
string or number | body |
Determines whether the SSL certificate of the host for |
コードサンプル
Shell
curl \
-X PATCH \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/repos/octocat/hello-world/hooks/42/config \
-d '{"url":"url"}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /repos/{owner}/{repo}/hooks/{hook_id}/config', {
owner: 'octocat',
repo: 'hello-world',
hook_id: 42,
url: 'url'
})
Response
Status: 200 OK
{
"content_type": "json",
"insecure_ssl": "0",
"secret": "********",
"url": "https://example.com/webhook"
}
Notes
Repository webhook deliveries
webhook の受信
GitHub Enterprise Server で webhook ペイロードを送信するには、インターネットからサーバーにアクセスできる必要があります。 暗号化されたペイロードを HTTPS 経由で送信できるように、SSL の使用も強く推奨します。
webhook ヘッダー
GitHub Enterprise Server は、イベントタイプとペイロード識別子を区別するために、複数の HTTP ヘッダーも送信します。 詳細は「webhook ヘッダー」を参照してく� さい。
PubSubHubbub
GitHub は、すべてのリポジトリに対する PubSubHubbub のハブとして機能することもできます。 PSHB はシンプルな公開/サブスクライブプロトコルで、トピックが更新されたときにサーバーが更新を受信できるよう登録できます。 更新は HTTP POST リクエストでコールバック URL に送信されます。 GitHub リポジトリのプッシュに対するトピック URL のフォーマットは以下の通りです。
https://github.com/{owner}/{repo}/events/{event}
イベントには、任意の使用可能な webhook イベントを指定します。 詳しい情� �については、「webhook イベントとペイロード」を参照してく� さい。
レスポンスのフォーマット
デフォルトのフォーマットは、既存の post-receive フックから予想できます。すなわち、POST で payload
パラメータとして送信される JSON の本文です。 また、Accept
ヘッダまたは .json
拡張子で、Raw 形式の JSON 本文を受信するよう指定できます。
Accept: application/json
https://github.com/{owner}/{repo}/events/push.json
コールバック URL
コールバック URL は http://
プロトコルを使用できます。
# Send updates to postbin.org
http://postbin.org/123
サブスクライブ
GitHub PubSubHubbub のエンドポイントは http(s)://[hostname]/api/v3/hub
です。 curl でリクエストに成功すると、以下のように表示されます。
curl -u "user" -i \
http(s)://[hostname]/api/v3/hub \
-F "hub.mode=subscribe" \
-F "hub.topic=https://github.com/{owner}/{repo}/events/push" \
-F "hub.callback=http://postbin.org/123"
PubSubHubbub リクエストは複数回送信できます。 フックがすでに存在する� �合は、リクエストに従って変更されます。
パラメータ
名前 | 種類 | 説明 |
---|---|---|
hub.mode | string | 必� �。 subscribe または unsubscribe 。 |
hub.topic | string | 必� �。 GitHub リポジトリがサブスクライブする URI。 パスのフォーマットは /{owner}/{repo}/events/{event} としてく� さい。 |
hub.callback | string | トピックの更新を受信する URI。 |
hub.secret | string | 送信する本文コンテンツの ハッシュ署名を生成する共有秘密鍵。 GitHubからきたプッシュを、そのリクエストのボディをX-Hub-Signature もしくはX-Hub-Signature-256 ヘッダと比較して、検証できます。 詳細は、 PubSubHubbub のドキュメントを参照してく� さい。 |