Skip to main content

webhook について

Webhook を使うと、GitHub で特定のイベントが発生するたびに、外部の Web サーバーに通知を配信できます。

webhook について

Webhook を使用すると、ソフトウェア システムで発生するイベントにサブスクライブし、それらのイベントが発生するたびにサーバーに配信されるデータを自動的に受信できます。

Webhook を、API をポーリングする (API を断続的に呼び出す) のではなく、データが発生次第受信します。 Webhook では、Webhook の作成時に 1 度イベントに関与するだけで済みます。

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

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

GitHub

の Webhook について

Webhook を作成する際に、URL を指定し、GitHub で発生するイベントにサブスクライブします。 Webhook がサブスクライブされているイベントが発生すると、GitHub は、指定した URL にイベントに関するデータを含む HTTP 要求を送信します。 その URL で Webhook 配信をリッスンするようにサーバーが設定されている場合は、受信したときにアクションを実行できます。

たとえば、コードがリポジトリにプッシュされたとき、pull request が開かれたとき、GitHub Pages サイトがビルドされたとき、または新しいメンバーがチームに追加されたときに発生するイベントに Webhook をサブスクライブできます。 サーバーは、コードを運用環境にデプロイするか、CI パイプラインをトリガーするか、通知を送信するか、新しいチーム メンバーの GitHub プロジェクトを作成することで応答できます。

Webhook は、特定のリポジトリ、組織、GitHub Enterprise, GitHub Marketplace アカウント、GitHub Sponsors アカウント、またはGitHub App 内に作成する必要があります。 その Webhook は、リポジトリ、組織、GitHub Enterprise、GitHub Marketplace アカウント、GitHub Sponsors アカウント、またはインストールされている GitHub App 内で使用可能なリソースのみにアクセスできます。 詳しくは、「Webhook の種類」を参照してください。

Webhook の作成の詳細については、「webhookの作成」を参照してください。 サブスクライブできるイベントの種類の詳細については、「Webhook のイベントとペイロード」を参照してください。 ペイロードの配信に応答してアクションを実行するようにサーバーを構成する方法の詳細については、「webhookの配信の取り扱い」を参照してください。

: 現在、GitHub Webhook では IPv6 はサポートされていませんが、今後サポートされる予定です。 /meta REST API エンドポイントは、その遷移を有効にするための IPv6 範囲を返します。

Webhook または REST API の選択

Webhook には、API を使用する場合と比較して、次のような利点があります。

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

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

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

注: GitHub Services (サービス フックとも呼ばれます) は、Webhook との統合を優先して、2019 年に非推奨となりました。 GitHub Services の使用から Webhook の使用への統合へ移行する方法の詳細については、このブログ記事を参照してください。

参考資料