Webhook のイベントとペイロード

Webhook イベントとペイロードについて

このページに表示されているイベントをサブスクライブする webhook を作成できます。 サーバーへの HTTP 要求の数を制限するには、扱う予定の特定のイベントだけをサブスクライブする必要があります。 詳しくは、「webhookの作成」をご覧ください。

このページの各 webhook イベントには、そのイベントの webhook プロパティの説明が含まれています。 イベントに複数のアクションがある場合は、各アクションに対応するプロパティが含まれます。

各イベントは、特定の種類の Webhook でのみ使用できます。 たとえば、組織の Webhook は team イベントにサブスクライブできますが、リポジトリの Webhook はサブスクライブできません。 各 Webhook イベントの説明に、そのイベントの可用性を一覧で示します。 詳しくは、「Webhook の種類」をご覧ください。

sender プロパティ

ほとんどの webhook ペイロードには、イベントをトリガーしたユーザーを識別する sender プロパティが含まれています。 イベントがユーザーではなく内部プロセスから発生した場合や、トリガー アクションにユーザーが関連付けられていない場合など、特定のユーザーを解決できない GitHub があります。 check_runやcheck_suiteなどの一部のイベントには、Git プッシュや認証済み API アクターのないアクションが含まれます。

このような場合、sender には、ghost が であり、login が実在する現在のユーザーに関連付けられていないプレースホルダー アカウントである id が設定されます。 senderは常にイベントの原因となった人物を識別し、それに依存するセキュリティまたはビジネス ロジックでghost ユーザーを考慮するとは限りません。

ペイロードの上限

ペイロードの上限は 25 MB です。 イベントにより大きなペイロードが生成された場合、GitHub はその webhook イベントのペイロードを配信しません。 これは、たとえば、多数のブランチまたはタグが一度にプッシュされた場合に、create イベントで発生する可能性があります。 確実にデリバリが行われるよう、ペイロードサイズを監視することをお勧めします。

配信ヘッダー

webhook によって設定されている URL エンドポイントに配信される HTTP POST ペイロードには、いくつかの特別なヘッダが含まれています。

• X-GitHub-Hook-ID: webhook の一意識別子。
• X-GitHub-Event: 配信をトリガーしたイベントの名前。
• X-GitHub-Delivery: イベントを識別するためのグローバルに一意な識別子 (GUID)。
• X-Hub-Signature: このヘッダーは、Webhook が secret で構成されている場合に送信されます。 これは要求本文の HMAC 16 進ダイジェストであり、SHA-1 ハッシュ関数と secret (HMAC key として) を使用して生成されます。 X-Hub-Signature は、既存の統合との互換性のために提供されています。 代わりに、さらに安全な X-Hub-Signature-256 の使用をおすすめします。
• X-Hub-Signature-256: このヘッダーは、Webhook が secret で構成されている場合に送信されます。 これは要求本文の HMAC 16 進ダイジェストであり、SHA-256 ハッシュ関数と secret (HMAC key として) を使用して生成されます。 詳しくは、「Webhook 配信を検証する」をご覧ください。
• User-Agent: このヘッダーには常にプレフィックス GitHub-Hookshot/があります。
• X-GitHub-Hook-Installation-Target-Type: Webhook が作成されたリソースの種類。
• X-GitHub-Hook-Installation-Target-ID: Webhook が作成されたリソースである一意 識別子。

Webhook ペイロード内の各ヘッダーの表示を確認するには、「Webhook 配信の例」を参照してください。

Webhook 配信の例

ペイロードは JSON 形式 (application/json) または URL エンコードしたデータ (x-www-form-urlencoded) として配信することができます。 JSON 形式を使用する webhook POST 要求の例を次に示します。

> POST /payload HTTP/1.1

> X-GitHub-Delivery: 72d3162e-cc78-11e3-81ab-4c9367dc0958
> X-Hub-Signature: sha1=7d38cdd689735b008b3c702edd92eea23791c5f6
> X-Hub-Signature-256: sha256=d57c68ca6f92289e6987922ff26938930f6e66a2d161ef06abdf1859230aa23c
> User-Agent: GitHub-Hookshot/044aadd
> Content-Type: application/json
> Content-Length: 6615
> X-GitHub-Event: issues
> X-GitHub-Hook-ID: 292430182
> X-GitHub-Hook-Installation-Target-ID: 79929171
> X-GitHub-Hook-Installation-Target-Type: repository

> {
>   "action": "opened",
>   "issue": {
>     "url": "https://api.github.com/repos/octocat/Hello-World/issues/1347",
>     "number": 1347,
>     ...
>   },
>   "repository" : {
>     "id": 1296269,
>     "full_name": "octocat/Hello-World",
>     "owner": {
>       "login": "octocat",
>       "id": 1,
>       ...
>     },
>     ...
>   },
>   "sender": {
>     "login": "octocat",
>     "id": 1,
>     ...
>   }
> }