GitHub Webhooks は、リポジトリで起きたイベントを外部の自動化処理に橋渡しする仕組みだ。CI/CD のトリガーや、社内ツールとの連携の入口として広く使われている。
イベントの粒度
push、pull_request、issues、release に加えて、workflow_run や deployment まで、開発フローのほぼあらゆる節目をイベントとして購読できる。設定はリポジトリ単位だけでなく組織単位でも可能なので、複数リポジトリ横断の自動化基盤を組むときにも扱いやすい。
使いどころ
GitHub Actions だけで完結しないワークフロー——たとえば PR が開いたら社内の Slack 以外の独自ダッシュボードに反映する、release が出たら外部のデプロイシステムを叩く——といった「GitHub の外」との連携でこそ Webhook の出番になる。Actions 内で完結する処理ならワークフローファイルで済むため、Webhook はあくまで外部システムとの橋渡し役と位置づけたい。
セキュリティと運用
HMAC 署名検証に対応しているので、受信側で必ず検証を入れ、第三者からの偽イベント送信を弾く。エンドポイントが一時的に落ちても、GitHub 側の再配信があるため受信ハンドラは冪等に作っておくのが安全だ。
受信側のスケールで気をつける点
活発なリポジトリや組織単位の購読では、イベントが短時間に集中して届くことがある。受信エンドポイントで重い処理を同期的に走らせると、応答が遅れて配信タイムアウトと再送を招く悪循環に陥りやすい。Webhook ハンドラは「受け取って即座にキューに積む」だけにとどめ、実処理は非同期ワーカーに回す構成が定石だ。
無料で使える。当然ながら GitHub 以外の Git ホスティング（GitLab や Bitbucket）のイベントは対象外で、それぞれ別の Webhook 機構を使うことになる。
配信の失敗に気づく仕組み
Webhook の配信は、受信側が落ちていれば失敗する。GitHub の管理画面には配信履歴が残り、個別に再送もできるが、能動的に見に行かなければ失敗に気づけない。連携が業務に組み込まれている場合、受信側で「一定時間イベントが来ていない」ことを検知する仕組みを持っておくと、静かに壊れた状態を避けられる。
巨大なコミットや大量のファイル変更を含むイベントでは、ペイロードに全情報が入らないことがあります。Webhook で受け取った情報だけで完結する設計にせず、必要に応じて API で詳細を取得する構えにしておいてください。
組織単位で設定するという選択
リポジトリごとに Webhook を設定すると、リポジトリが増えるたびに設定漏れが起きる。組織レベルで設定すれば、配下のリポジトリすべてのイベントを一箇所で受けられる。受信側でリポジトリ名によるフィルタが必要になるが、設定の管理という観点では組織単位のほうが破綻しにくい。GitHub App として実装すれば、インストール単位でさらに管理しやすくなる。