webhook について

webhook について

Webhook は、ユーザーがソフトウェア システムで発生するイベントをサブスクライブできる通信方法です。 Webhook は、GitHub で特定のイベントが発生するたびにトリガーされます。 たとえば、以下のような場合にトリガーするように Webhook を設定できます。

• リポジトリへのコードのプッシュ
• プルリクエストのオープン
• GitHub Pagesサイトの構築
• Team への新しいメンバーの追加

GitHub Enterprise、Organization、リポジトリ、または GitHub App.

各インストール対象 (GitHub Enterprise Server インスタンス、特定の Organization、または特定のリポジトリ) のイベントごとに最大 250 の Webhook を作成できます。

Webhook の作成の詳細については、「webhookの作成」を参照してください。

Webhook イベントについて

Webhook を構成する際に、ペイロードが送信されるイベントを選択できます。 サーバーへの HTTP 要求の数を制限するには、扱う予定の特定のイベントのみをサブスクライブする必要があります。 すべての Webhook イベントとそのペイロードの完全な一覧については、「Webhook のイベントとペイロード」を参照してください。

一部の Webhook イベントにはアクションがあります。これは、Webhook イベントが表すリソースに対して実行できる操作です。 Webhook イベントに複数のアクションの種類がある場合、各アクションによってペイロードの配信がトリガーされます。 たとえば、package Webhook イベントは、パッケージが updated か edited の場合にペイロードの配信をトリガーします。 個々の Webhook アクションをサブスクライブすることはできません。 Webhook を構成すると、その Webhook に関連するすべてのアクションのペイロードを受信することになります。

既定では、GitHub Enterprise、Organization またはリポジトリにインストールされている Webhook は、push イベントにのみサブスクライブされます。 既定では、GitHub Apps の Webhook はどのイベントにもサブスクライブされません。 Webhook がサブスクライブされるイベントはいつでも変更できます。

Webhook の配信について

Webhook 配信を受信すると、ペイロードには、配信をトリガーしたイベントとアクションの名前と、イベント自体に関するその他の情報が含まれます。 各ペイロードに含まれる配信ヘッダーの詳細と配信例については、「Webhook のイベントとペイロード」を参照してください。 一部の情報は、イベントを実行したユーザー、イベントが発生した Organization またはリポジトリなど、ほとんどの Webhook 配信またはすべての Webhook 配信に含まれます。

Webhook を作成する際には、Webhook イベントを受信する URL を指定する必要があります。 Webhook がサブスクライブされているイベントが発生すると、GitHub によって、この URL に HTTP POST ペイロードが送信されます。 その後、サーバーは Webhook を処理して応答できます。 詳しくは、「webhookの配信の取り扱い」を参照してください。

Webhook 配信の表示については、「webhookの配信の表示」を参照してください。

Webhook を使用する場面

Webhook は、次のようなさまざまなシナリオで使用できます。

• 外部 CI サーバーで CI (継続的インテグレーション) パイプラインをトリガー。 たとえば、コードがブランチにプッシュされたときに Jenkins または CircleCI で CI をトリガーします。
• GitHub のイベントに関する通知をコラボレーション プラットフォームに送信。 たとえば、プル要求に関するレビューがある場合に Discord または Slack に通知を送信します。
• Jira などの外部イシュー トラッカーを更新。
• プロダクション サーバーへのデプロイ。
• GitHub で発生したイベントを監査目的でログに記録。

Webhook を使用すると、API を断続的に呼び出してデータが使用可能かどうかを確認する (更新のポーリングともいう) のではなく、発生時にデータを受信できます。 Webhook を作成するときに、イベントに関心を 1 回示すだけで済みます。

Webhook には、API を使用する場合よりも優れる次の利点があります。

• Webhook では、API をポーリングするよりも少ない労力とリソースで済みます。
• Webhook は API 呼び出しよりもスケーリングで優れています。 多くのリソースを監視する必要がある場合は、各リソースに対して API を呼び出すと、すぐに API レート制限クォータに達する場合があります。 代わりに、複数の Webhook イベントをサブスクライブし、イベントが発生したときにのみ情報を受信できます。
• Webhook はイベントが発生したときにトリガーされるため、ほぼリアルタイムの更新が可能です。

情報が 1 回だけ必要な場合、または断続的に必要な場合、またはスケールアップする予定のない小規模のリソースから情報を取得するだけの場合は、関連情報が必要なときに API を呼び出すことができます。

Webhook を使用する際のベスト プラクティスについては、「Webhook の使用に関するベスト プラクティス」を参照してください。

Webhook を管理するための権限について

Webhook を管理するには、Webhook が作成され、イベントをリッスンしているリソースを所有するか、管理者アクセス権を持っている必要があります。 たとえば、Organization の Webhook を管理するには、その Organization の管理者権限が必要です。 さまざまな Webhook の種類の作成に関する詳細については、「webhookの作成」を参照してください。

従来の GitHub Services を Webhook に置き換える

GitHub Services (サービス フックという場合もある) は、GitHub がgithub-services リポジトリを介してインテグレーターのサービスの一部をホストした統合の従来の方法です。 2019 年、Webhook との統合を優先して GitHub Services は非推奨になりました。 この非推奨に関する詳細については、こちらのブログ記事を参照してください。