前回の続きと、この講義の役割
前回のK-06では、外部APIを利用する流れを6段階で確認しました。あの流れはどれも、こちらから相手のAPIを呼びに行く通信でした。今回のWebhookは、その向きが逆になります。相手側で決済の完了やメッセージの受信といった出来事が起きたとき、相手のほうからこちらへ通信が届くのです。「聞きに行く」だけだった連携に、「知らせが来る」という選択肢が加わります。この2方向を使い分けられるようになるのが、この講義の役割です。
このスライドのポイント
- K-06では、外部APIを利用する流れを6段階で見た（仕様確認・認証・送信・応答解析・失敗処理・利用制限）
- そこでの通信は、すべて「こちらから相手を呼ぶ」向きだった
- この講義では、その逆向きの連携を扱う
- 相手側の出来事をきっかけに、相手からこちらへ通信が来る
Webhookの定義
Webhookとは、相手側でイベントが起きたときに、相手があらかじめ登録されたこちらのURLへHTTPリクエストを送ってくる仕組みです。イベントとは、たとえば決済の完了やメッセージの受信のことです。K-06までに見た「こちらから相手を呼ぶ」通信とは、向きがちょうど逆になります。こちら側がすることは、知らせを受け取るための受け口を用意して待つことです。この受け口は、K-02で学んだエンドポイント、つまりJ-04で作ったルートそのものです。
このスライドのポイント
- Webhook＝相手側でイベントが起きたとき、相手があらかじめ登録されたこちらのURLへHTTPリクエストを送ってくる仕組み
- イベントの例: 決済完了、メッセージ受信、処理の終了
- K-06までの「こちらから呼ぶ」と向きが逆
- こちらは受け口（エンドポイント＝J-04のルート）を用意して待つ
なぜWebhookが必要か
Webhookを知らないと、「決済が終わったら自動で記録する」といった、実務でよくある仕組みを作れません。代わりに思いつくのは、こちらから相手へ「もう終わりましたか」と定期的に問い合わせ続ける方法です。これは通信の無駄が多く、知らせが届くまでに時間差も生まれます。相手側の出来事を、起きた瞬間に受け取れることがWebhookの価値です。同時に、受け口は外の世界へ公開されるため、無防備に置くと危険だという点にも、知っておかないと気づけません。
このスライドのポイント
- Webhookを知らないと「決済が終わったら自動で記録」のような仕組みが作れない
- 代わりに、こちらから定期的に問い合わせ続ける無駄な設計しか思いつかない
- 相手の出来事を、起きた瞬間に受け取れるのがWebhookの価値
- 受け口を無防備に公開する危険にも気づけない
向きの構造
2つの向きを図で整理します。API呼び出しは、こちらから相手へ問い合わせ、その場で応答が返ってくる通信です。Webhookは、相手からこちらの受け口へ、出来事が起きるたびに通知が届く通信です。電話にたとえるなら、前者はこちらから電話をかける形、後者は電話がかかってくる形です。どちらも同じHTTPを使いますが、通信を始めるのがどちら側かが逆になっています。この「始める側」の違いが、設計の考え方を大きく変えます。
このスライドのポイント
- API呼び出し: こちら→相手へ問い合わせ、その場で応答が返る
- Webhook: 相手→こちらの受け口へ、出来事のたびに通知が届く
- たとえるなら「電話をかける」か「電話がかかってくる」か
- どちらもHTTPだが、通信を始める側が逆
処理の流れ
具体的な流れを、決済サービスとの連携で見てみます。利用者の支払いが完了した瞬間、決済サービス側が、あらかじめ登録されたこちらの受け口のURLへPOSTを送ってきます。こちらのサーバーは、その通知を受け取り、支払い済みとして記録を更新します。ここで大切なのは、こちらから「支払いは終わりましたか」と聞きに行っていないことです。相手側の出来事に合わせて、知らせのほうから届く。これがWebhookを使った連携の、基本的な流れです。
このスライドのポイント
- 例: 決済サービスとの連携
- 支払い完了の瞬間、相手がこちらの受け口 /api/webhooks/payment へPOSTを送る
- こちらのサーバーは、その通知を受け取って記録を更新する
- こちらから聞きに行かなくても、知らせのほうから届く
技術サンプル: 受信Webhookのリクエスト
これは、相手から送られてくる受信Webhookのリクエストを、擬似的に書き出したものです。読み方は3点です。1つ目、これは相手からこちらへのPOSTで、ボディにイベントの種別と関連データが入っています。2つ目、宛先はこちらが用意した受け口です。3つ目、この受け口は世界に公開されるため、誰でも偽の通知を送れてしまいます。そこで、送り主が本物かを確かめる署名の確認が欠かせません。値はすべてダミーです。仕組みの詳細はカテゴリQで扱います。
混同しやすい概念
ここで混同しやすいのが、API呼び出しとWebhookの区別です。API呼び出しは、こちらが始める通信で、応答はその場ですぐ返ってきます。始めるタイミングもこちらが決められます。一方Webhookは、相手が始める通信で、いつ届くかは相手側の出来事しだいです。こちらは待つことしかできません。つまり、通信を始める側と、そのタイミングの主導権が、両者でちょうど逆になっているのです。同じ連携でも、この主導権の違いを意識すると、設計の見通しがよくなります。
バイブコーディングでの確認点
バイブコーディングでWebhookの受け口をAIに作らせたら、確認してほしいことが2点あります。1つ目は、送り主が本物かを確かめる署名の確認があるかどうかです。これがないと、偽の通知をそのまま信じてしまいます。2つ目は、同じ通知が2回届いたときに、二重処理にならないかどうかです。AIへは、たとえば「このWebhook受け口は、送り主が本物かをどう検証していますか」と質問します。2つ目の備えについては、カテゴリKの最終回でさらに詳しく扱います。
このスライドのポイント
- Webhookの受け口をAIに作らせたら、次の2点を必ず確認する
- ①送り主が本物かを確かめる署名の確認があるか
- ②同じ通知が2回届いたとき、二重処理にならないか
- ②の備えは、カテゴリKの最終回でさらに詳しく扱う
まとめと次回
最後に一問一答です。相手側の出来事を、こちらに知らせてくる仕組みを何と呼ぶでしょうか。……答えはWebhookです。30秒でまとめます。APIはこちらから聞きに行く通信、Webhookは向こうから知らせが届く通信で、両者は向きが逆でした。そして受け口は世界に公開されるため、送り主が本物かの検証を忘れてはいけません。次回のK-08では、時刻を引き金にする定期実行を扱います。関連資料の「Webhook入門」と「n8n自動化レシピ50」も、あわせてご覧ください。
このスライドのポイント
- 一問一答: 相手側の出来事をこちらに知らせてくる仕組みは？ → Webhook
- 30秒まとめ: APIは「こちらから聞く」、Webhookは「向こうから知らせる」。受け口は公開されるので、送り主の検証を忘れない
- 次回K-08: 時刻を引き金にする定期実行へ
- 関連資料: 「Webhook入門」「n8n自動化レシピ50」
