Webhook とは？イベント駆動の HTTP コールバック

webhook はユーザー定義の HTTP コールバックです。何かが起きると、サービスはあなたが登録した URL に HTTP リクエストを送信し、ポーリングさせる代わりにイベントをあなたにプッシュします。

「まだ新しいものはある？」と API を繰り返しポーリングするのは無駄です。webhook はそれを逆転させます。サービスに URL を渡すと、イベントが発生した瞬間にその URL へ POST します。push、merge、release は webhook を通じて CI をトリガーし、イベント駆動パイプラインの土台となります。

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

プロバイダーにエンドポイントを登録します。一致するイベントが発生すると、プロバイダーはそれを記述した payload を伴う HTTP POST を送信します。あなたのサービスは、次のポーリングで変更を発見するのではなく、即座に反応します。

CI の webhook をトリガーするもの

ブランチへの push。
pull request のオープンまたは更新。
tag または release の作成。
deployment のステータス変更。

真正性の検証

誰でもあなたの URL へ POST できてしまうため、プロバイダーは共有シークレットで payload に署名します。受信側はリクエストを信頼する前に署名を検証し、これによりなりすましイベントがパイプラインをトリガーするのを防ぎます。

配信はベストエフォート

あなたのエンドポイントが一時的にダウンしていたり遅かったりすると、webhook は取りこぼされることがあります。優れたプロバイダーは失敗した配信をリトライし、試行のログを公開するため、届かなかったイベントを再送できます。

CI/CD における webhook

パイプラインを開始するイベントは、通常はソースホストからの webhook です。デプロイも、たとえば release 完了時にチャットチャンネルに通知したりステータスページを更新したりするために、webhook を外向きに送信します。

一時的な配信失敗

一瞬の不具合の間に受信側が 5xx を返すと、プロバイダーは後でリトライするため、短時間の障害でイベントが失われることはめったにありません。Latchkey の runner エンドポイントは一時的な不具合を許容し、プロバイダーのリトライに依存するため、1 回の配信失敗が build のトリガーを暗黙のうちに取りこぼすことはありません。

重要なポイント

webhook は、ポーリングされる代わりにイベントをプッシュする HTTP コールバックです。
payload は署名されるため、受信側はそれが本物であることを検証できます。
配信はリトライ付きのベストエフォートなので、受信側は idempotent になるよう設計してください。