Webhookアーキテクチャとは? システム間のプッシュ通知

Webhookアーキテクチャは、イベントが起きたときに登録されたURLへHTTPリクエストを送ることで、あるシステムが別のシステムに通知できるようにします。

Webhookは、システム同士がインターネット越しにイベントをプッシュする方法です。あるシステムが別のシステムに変化をポーリングするのではなく、何かが起きた瞬間に、送信元システムがあなたの登録したURLを呼び出します。プッシュ時にGitHubがワークフローを発火させること、支払いをStripeが通知することは、いずれもWebhookアーキテクチャであり、ほとんどのCI/CDトリガーのバックボーンです。

ポーリングではなくプッシュ

プロバイダーにコールバックURLを登録し、どのイベントに関心があるかを伝えます。そのイベントが発生すると、プロバイダーは何が起きたかを記述したペイロードとともにHTTP POSTをあなたのURLに送ります。ポーリングは不要で、ほぼリアルタイムの配信です。

連携を支える理由

絶え間ないポーリングなしのリアルタイム反応。
送信元と受信側の疎結合。
どんなシステムでも実装できるシンプルなHTTP契約。
外部イベントでパイプラインをトリガーするのに自然に適合。

受信側の難所

エンドポイントは、本物の配信だけを信頼するよう署名を検証し、送信側がタイムアウトしないよう素早く応答し、重複配信を冪等に処理しなければなりません。プロバイダーは失敗時にリトライするため、同じイベントが複数回届きうります。

WebhookとCI/CD

pushやpull requestのWebhookが、ほとんどのパイプラインを開始させます。Webhook受信側がそのイベントをビルドに変換するため、その信頼性はCIが動くかどうかそのものに直結します。取りこぼしたり検証されなかったりしたWebhookは、取りこぼしや悪意あるビルドを意味します。

リトライを想定した設計

送信側は2xx以外の応答でリトライするため、不安定な受信側は重複処理を引き起こします。冪等な処理、素早い確認応答、そしてエンドポイントの背後で実際の作業をキューイングすることが、リトライ下でもWebhookアーキテクチャを信頼できるものに保ちます。

Latchkeyについての補足

Latchkeyは、jobがキューに入った瞬間にGitHubのWebhookからマネージドrunnerを起動します。そのトリガーはプッシュベースであるため、Webhook経路の信頼性こそが、runnerがどれだけ速くオンラインになるかを決めます。

重要なポイント

Webhookアーキテクチャは、イベントをポーリングする代わりにHTTP経由でプッシュします。
受信側は署名を検証し、素早く応答し、重複配信を処理しなければなりません。
Webhookは、外部イベントからほとんどのCI/CDパイプラインをトリガーするものです。