Webhook

development network beginner

特定の出来事が起きたときに、あらかじめ登録しておいたURLへ自動的にデータを送信する仕組み。

概要（サマリー）

Webhookとは、あるシステムで特定の出来事（イベント）が起きたときに、そのシステム側から、あらかじめ登録しておいたURLへ向けて自動的にデータを送信する仕組みのことである。

たとえば、GitHubにコードをプッシュしたときや、決済サービスで支払いが完了したときに、その通知を自分のサーバーへ即座に届けてもらうために使われる。通常のAPIが「こちらから質問して答えをもらう（電話をかける）」仕組みだとすると、Webhookは「向こうから知らせが来るのを待つ（電話がかかってくる）」仕組みに近い。初心者向けには、「何かが起きたら自動的に連絡してくれる仕組み」と考えるとわかりやすい。

詳細解説

Webhookは「向こうから知らせてくれる」仕組みである

外部システムの変化を知る方法の1つに、こちらから定期的に「新しい情報はありますか？」とAPIへ問い合わせるポーリングがある。この方法は実装しやすい一方、変化がない間も問い合わせが発生する。

Webhookでは、あらかじめ「何か起きたら、このURLへ知らせてください」と登録しておくことで、実際にイベントが発生した瞬間だけ、相手側から自動的にデータが送られてくる。これにより、不要な問い合わせを減らしながら、リアルタイムに近い形で通知を受け取れる。

Webhookの基本的な流れ

Webhookの仕組みは、次のような流れで動く。

受け取る側が、自分のサーバーに「通知を受け取るためのURL（エンドポイント）」を用意する
通知を送る側のサービス（GitHub、Stripeなど）の管理画面で、そのURLを登録する
登録したイベント（プッシュ、支払い完了など）が実際に発生する
サービス側が、登録済みのURLへ向けて自動的にHTTPリクエストを送信する
受け取る側のサーバーが、送られてきたデータ（ペイロード）を処理する

代表的な利用例

Webhookは、さまざまなサービス間の自動連携でよく使われている。

GitHub: コードのプッシュやプルリクエストの作成などをトリガーに、CI/CDツールへ自動通知する
決済サービス: クレジットカード決済が完了したタイミングで、自社サーバーへ通知し、注文処理を自動化する
チャットツール連携: サーバーや連携サービスがフォームの送信内容を受け取り、SlackやDiscordのチャンネルへ自動投稿する
CMSやWebサービス: 記事の公開や更新をトリガーに、他のサービスへ通知する

コード例（Webhookを受け取るサーバー側の処理）

以下は、Node.js（Express）でWebhookのリクエストを受け取り、送られてきたJSONデータを処理する簡単な例である。

const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhook', (req, res) => {
  const payload = req.body;

  console.log('受信したイベント:', payload);

  res.status(200).send('OK');
});

app.listen(3000);

この例は受信の流れを示す最小構成であり、実運用でそのまま使ってはならない。実際には、送信元の仕様に従って署名を検証し、想定したイベントだけを処理する。署名検証で生のリクエスト本文が必要かどうかも、利用サービスの公式文書で確認する必要がある。

セキュリティ上の注意点

Webhookは外部から自動的にリクエストが送られてくる仕組みであるため、悪意のある第三者が偽のリクエストを送りつけてくる可能性がある。

多くのサービスでは、送信内容が正規のものか確認するための署名（シグネチャ）をリクエストに含めている。受信側は各サービスの仕様に従って署名を検証し、HTTPSを使い、必要に応じて送信時刻やイベント識別子も確認する。URLを推測しにくくするだけでは、認証や署名検証の代わりにはならない。

AIコーディングとの関係

AIに「外部サービスと連携する機能を作って」と依頼すると、Webhookを使った実装を提案されることがある。

たとえば、次のように指示すると効果的である。

「GitHubのWebhookから送られてくるプッシュイベントを受け取り、Slackへ通知するNode.jsのコードを書いて」
「Stripeの決済完了Webhookを受け取る際、署名を検証して不正なリクエストを弾く処理を追加して」

AIが生成したWebhook受信コードを確認する際は、利用サービスの公式手順に沿った署名検証、重複配信を考慮した冪等な処理、想定外のイベントへの対応が含まれているかを確認するとよい。

よくある勘違い

WebhookとAPIは同じもの？

同じものではない。APIはソフトウェア同士が機能やデータをやり取りするための広い仕組みである。Webhookは、イベントの発生時に提供元から受信側のURLへHTTPリクエストを送る連携パターンである。Webhookの受信窓口も、HTTP APIのエンドポイントとして実装されることが多い。

Webhookを設定すれば、送信元の安全性は自動で保証される？

そうではない。Webhookは外部から自動的にリクエストが届く仕組みであるため、受信側で送信元と内容を検証する必要がある。提供元が署名検証を用意している場合はその公式手順に従い、別の認証方式が指定されている場合はそれを使う。

Webhookのリクエストは必ず1回だけ届く？

そうとは限らない。通信の不具合などにより、同じイベントの通知が複数回届くことがある。重要な処理では、同じ内容を2回処理してしまわないよう、受信側で重複チェックの仕組みを用意することが望ましい。

まとめ

Webhookは、特定のイベントが起きたときに、登録済みのURLへ自動的にデータを送信する仕組みである。
定期的な問い合わせ（ポーリング）と違い、必要なときだけ通知が届くため効率的である。
GitHubの通知や決済完了通知など、サービス間の自動連携でよく使われる。
受け取る側は、署名検証などのセキュリティ対策を自分で実装する必要がある。
同じ通知が複数回届く可能性を考慮し、重複処理を防ぐ設計が望ましい。

情報ソース

GitHub Docs: Webhook について

より詳しくAIに聞いてみよう

WebhookとAPIの違いを、電話にたとえて初心者向けに説明してください。
GitHubのWebhookを使って、コードがプッシュされたときに自動でデプロイを走らせる仕組みを教えてください。
Webhookの署名（シグネチャ）検証の仕組みと、実装方法をコード例つきで教えてください。
Webhookのリクエストが重複して届く場合の、安全な処理方法（冪等性の確保）を教えてください。
AIにWebhook連携機能を実装してもらうとき、セキュリティ面で確認すべきポイントを教えてください。