Webhookとは、出来事が起きた時に、相手のサーバがこちらの決めた URL へ HTTP で知らせを送る仕組みです。
- Webhook の仕組みと、API を呼びに行く形との違い、HMAC 署名で送り手を確かめる考え方
- 当社の決済の受け口が、テストの知らせに 401 を返し続けて、送り手に自動で止められた記録と直し方
- 受信箱方式・重複の止め方・署名の確かめ・見張り・本番の受け口へのテストの撃ち方
ウェブフック、Web フックと書かれる物も同じ仕組みです。当社は AIエージェント の席に受け口の実装と運用を任せていて、この頁は公式の文書の定義に、決済・LINE・Meta の知らせを受けて実際に踏んだ記録を並べた物です。受け口を置く先は Cloud Run、合言葉の保管は Secret Manager、決まった時刻に呼ぶ側の仕組みは Cloud Scheduler の頁にあります。
Webhook の仕組み:出来事・送り手・Webhook URL・受け口
GitHub の文書は、Webhook を「ソフトウェアの中で起きる出来事を購読し、その出来事が起きるたびにデータを自動で受け取る」仕組みとし、指定した URL へ出来事のデータを載せた HTTP の要求を送ると書いています(GitHub Docs「About webhooks」・2026-11-09 に確認)。この URL を Webhook URL(エンドポイント)と呼び、受ける側のサーバの口を、この頁では受け口と呼びます。
| 順 | 起きる事 | 受け口の側で決める事 |
|---|---|---|
1 | 送り手の管理画面か API で、Webhook URL と受けたい出来事の種類を登録する | 公開の HTTPS の URL を用意する。秘密の値を URL に入れない |
2 | 出来事が起きると、送り手が Webhook URL へ HTTP の要求(多くは POST)を送る | 署名か合言葉で、本物の送り手かを確かめる |
3 | 受け口が 2xx を返すと届いた扱い。2xx 以外や時間切れは失敗の扱いになる | 重い処理の前に、早く 2xx を返す |
4 | 失敗すると、送り手は時間を置いて再送する | 同じ知らせが何度来ても 1 回だけ処理する |
出典: GitHub は受け口が 10 秒以内に 2xx を返すよう求め、遅い応答を失敗として数えます(GitHub Docs「Best practices for using webhooks」・2026-11-09 に確認)。Meta は届かなかった知らせを最大 36 時間再送すると書いています(Meta「Getting Started」・2026-11-09 に確認)。
Webhook と API の違い:どちらが話を始めるか
| 見る所 | API を呼ぶ(取りに行く) | Webhook(知らせが来る) |
|---|---|---|
話を始める側 | こちら | 相手のサーバ |
いつ届くか | こちらが呼んだ時だけ。変化を知るには間を置いて呼び続ける(ポーリング) | 出来事が起きた時 |
こちらが用意する物 | API の鍵と、呼ぶ処理 | 外から届く公開の URL と、受ける処理 |
取りこぼし | 呼ぶ間隔の中の変化に遅れる | 受け口が止まっている間の知らせは、送り手の再送が頼り |
GitHub の文書は、API を間を置いて呼ぶ形に対して、Webhook は出来事を購読する意思を作る時に 1 回示せば足りると書いています(GitHub Docs「About webhooks」・2026-11-09 に確認)。両方を合わせる使い方もあります。Stripe の文書には、知らせを取り損ねた時に API で出来事の一覧を引き直して処理する手順が載っています(Stripe Docs「Webhook エンドポイントを管理する」・2026-11-09 に確認)。
HMAC 署名とは:共有の合言葉で、送り手と中身を確かめる
Webhook URL は外に開いているので、誰でも偽の知らせを送れます。そこで多くの送り手は、こちらと共有した秘密の値(合言葉)で本文に署名して送ります。HMAC は、ハッシュ関数 H と秘密の鍵 K を使い、H(K XOR opad, H(K XOR ipad, text)) で本文の認証の値を作る方式です(RFC 2104・2026-11-09 に確認)。受け口は、届いた本文と自分の持つ合言葉で同じ計算をし、見出しの署名と一致した物だけを処理します。
| 送り手 | 署名の見出し | 鍵と方式 |
|---|---|---|
GitHub | X-Hub-Signature-256(sha256= で始まる) | Webhook の secret で HMAC-SHA256。16 進の値 |
Meta(Instagram・Messenger) | X-Hub-Signature-256(sha256= で始まる) | アプリの App Secret で SHA256 の署名 |
LINE | x-line-signature | チャネルシークレットで HMAC-SHA256。文書の例は base64 にした値で比べる |
出典: GitHub Docs「Validating webhook deliveries」・Meta「Getting Started」・LINE Developers「Verifying webhook signatures」(いずれも 2026-11-09 に確認)。
実装で外しやすい所は 2 つです。1 つは本文を加工してから計算する事で、LINE も Stripe の文書も、受け取った生の本文で確かめるよう書いています。JSON に読み直してから計算すると一致しません。もう 1 つは比べ方で、GitHub は普通の等号でなく、時間が一定の比較(例: crypto.timingSafeEqual)を勧めています(同上の各頁・Stripe Docs・2026-11-09 に確認)。
当社の記録:テストの知らせへの 401 で、決済の受け口が止められた
決済の知らせを受ける当社の受け口は、合言葉は合っているがモード(テスト/本番)の違う知らせを 401(拒否)で返していました。決済会社はテストの知らせを 20 本再送し、20 本とも 401 だったため、その Webhook を自動で「停止」にしました(社の実測 2026-10-21)。
| 時 | 起きた事 |
|---|---|
2026-10-20〜21 | テストの知らせが届き、受け口がモード違いを理由に 401 を返す |
再送の間 | 決済会社が 20 本再送し、20 本とも 401 |
20 本目の後 | 決済会社がその Webhook を自動で停止。本番の知らせも届かなくなる |
停止の約 1 時間半 | 本番の知らせが 0 本。決済の画面が「処理しています」のまま止まり、ここで気づいた |
気づいた後 | 決済会社の管理画面で Webhook を有効に戻し、知らせが再開 |
出典: 社の実測 2026-10-21。
401 は「お前は誰だ」という返事で、送り手から見ると受け口が壊れているのと区別できません。モードの違いは「本物だが、この受け口では使わない知らせ」であって、偽物ではありませんでした。拒否の返事を続けると、送り手は再送を重ね、やがて Webhook ごと止めます。止まると、テストだけでなく本番の知らせも止まります。
直し方:合言葉を先に照らし、使わない本物は 200 で受けて捨てる
照合の順を入れ替えました。合言葉の照合を先にし、合わない物は今までどおり 401 です。合言葉は合うがモードの違う物は 200 で受けて捨て、受信箱に入れません。これで再送が止まります(社の実測 2026-10-21)。
| 届いた知らせ | 返す | 受信箱 | 送り手の動き |
|---|---|---|---|
合言葉が合う・モードも合う | 200 | 入れる | 届いた扱い |
合言葉が合う・モードが違う | 200 | 入れない(捨てる) | 届いた扱い=再送しない |
合言葉が違う・空 | 401 | 入れない | 失敗の扱い |
直した後に撃って確かめました。合う合言葉+テストのモードは 200、違う合言葉は 401 でした(社の実測 2026-10-21)。
合言葉そのものの持ち方も、先に決めてありました。照合の合言葉は会社(テナント)ごとに持ち、空や不一致は 401 の 1 本の道にしています。自社だけの特別な抜け道(全社に通る共通の合言葉)は残していません(社の決め 2026-10-07)。拒否の道を 1 本にしておくと、上の表の「どの知らせに何を返すか」を 1 か所で決められます。
止まった Webhook を、15 分ごとに見に行く
停止に気づくまでの約 1 時間半は、決済の画面が止まって初めて分かった時間でした。そこで、15 分ごとに Webhook が届く状態かを確かめ、止まっていたら知らせる仕組みを作りました。わざと 1 本止めて撃つと、知らせが立ちました(社の実測 2026-10-21)。
作る途中で分かった事が 2 つあります(社の実測 2026-10-21)。
| 分かった事 | 見張りの作りに効いた所 |
|---|---|
決済会社の Webhook の一覧は、止めた Webhook を返さない | 「状態が停止」を探しても出ない。在るはずの Webhook が「一覧に無い」事で止まりを判じる |
ログの一致で知らせる決まりは、作ってから効くまで数分かかる | 作った直後の 1 回目は知らせが立たなかった。見張りを足したら、数分置いてからわざと止めて確かめる |
受信箱方式:表に入れてから 200、処理は別に回す
送り手は早い 2xx を求めます。GitHub は 10 秒以内とし、処理はキューで非同期に回すよう勧めています(GitHub Docs・2026-11-09 に確認)。ただし「200 を先に返してから、同じ要求の中で重い処理を続ける」作りは、Cloud Run の既定では危うい形です。既定の要求ごとの課金では、CPU は要求を処理している間だけ割り当てられ、応答を返した後の処理には向きません(Google Cloud「課金の設定」・2026-11-09 に確認)。
当社はそこで、知らせをまず受信箱の表に入れて 200 を返し、処理は別に回す形(受信箱方式)にしました(社の決め 2026-09-28)。
| 作り | 200 を返す時 | 返した後の処理 |
|---|---|---|
同じ要求の中で処理してから 200 | 処理が終わってから | —(重いと時間切れで失敗の扱い) |
200 を先に返し、同じ要求の中で処理を続ける | すぐ | CPU の絞られた状態で走る(Cloud Run の既定) |
受信箱方式(当社) | 受信箱の表に入れた直後 | 別の処理が表から拾って回す |
直した後に試しの知らせ 2 本を撃つと、応答は 1.587 秒と 0.451 秒で、受信箱の処理済みが 2、失敗が 0 でした(社の実測 2026-09-28)。
受信箱は重複を止める場所にもなります。送り手は同じ知らせを再送するので、当社は知らせの一意の鍵を DB が止める形にし、同じ知らせの再送を 1 回だけ処理しています。確かめた時の重複の数は 0 でした(社の実測 2026-10-20)。GitHub も、配達ごとの ID(X-GitHub-Delivery)で重複を見分けるよう書いています(GitHub Docs・2026-11-09 に確認)。
Webhook のセキュリティ:別の鍵の署名は 403、合言葉は URL に置かない
Meta(Instagram・Messenger)の受け口で、署名の確かめを 3 通り撃ちました(社の実測 2026-11-08)。
| 撃った知らせ | 返った |
|---|---|
使っているアプリの鍵で署名 | 200 |
別のアプリの鍵で署名 | 403 |
署名なし | 403 |
出典: 社の実測 2026-11-08。「署名が在るか」だけでなく、「この受け口の鍵で作った署名か」まで確かめている事を、別の鍵の行で見ています。Meta の文書は署名の確かめを任意としつつ勧めています(Meta「Getting Started」・2026-11-09 に確認)。
もう 1 つは置き場の失敗です。受け口の確かめ用の合言葉(verify token)が受け口の URL に入っていて、Cloud Run のログに平文で出ていました(社の実測 2026-08-28)。要求の URL はクエリごとログに残るので、秘密を URL のクエリに置くと、ログを読める人すべてに見えます。GitHub の文書も、Webhook URL に資格情報を入れないよう書いています(GitHub Docs・2026-11-09 に確認)。合言葉は見出しの署名で確かめ、値は Secret Manager のような保管庫から読む形にします。
Webhook のテスト:本番の受け口へ、署名つきの知らせを自分で作って撃つ
送り手の管理画面の「テスト送信」は、届くかどうかしか分かりません。当社は LINE の知らせを、本番の受け口へ署名つきで自分で作って撃ち、5 本とも 200 を確かめた上で、その後の動き(BOT の返事)を読み返して確かめました(社の実測 2026-10-24)。
| 確かめる事 | 撃つ物 | 当社で見た結果 |
|---|---|---|
本物が通る | 正しい鍵で署名した知らせ | LINE: 5 本とも 200・BOT の返事まで確認(社の実測 2026-10-24) |
偽物が落ちる | 別の鍵の署名・署名なし | Meta: 403・403(社の実測 2026-11-08) |
使わない本物で止められない | 合う合言葉+テストのモード | 決済: 200(社の実測 2026-10-21) |
合言葉違いは拒む | 違う合言葉 | 決済: 401(社の実測 2026-10-21) |
再送で二重に動かない | 同じ知らせをもう一度 | 重複の数 0(社の実測 2026-10-20) |
200 が返った事は「受け口が受け取った」事までしか示しません。受信箱方式では処理は後で走るので、その後の動き(返事・表の状態)まで読み返して、初めて通ったと言えます。
よくある質問
Webhook と API の違いは何ですか?
API はこちらから相手に問い合わせる形で、Webhook は出来事が起きた時に相手からこちらの URL へ知らせが来る形です。変化を待つなら、API を呼び続ける(ポーリング)より Webhook の方が遅れが小さくなります(GitHub Docs・2026-11-09 に確認)。
Webhook URL とは何ですか?
送り手が知らせを送る先として登録する、こちらのサーバの URL です。外から届く HTTPS の URL にし、合言葉などの秘密は URL に入れません。当社では URL に入れた合言葉が Cloud Run のログに平文で出ていました(社の実測 2026-08-28)。
HMAC 署名とは何ですか?
送り手とこちらだけが知る合言葉を鍵にして、本文から作る認証の値です(RFC 2104・2026-11-09 に確認)。受け口は生の本文で同じ計算をして、見出しの署名と一致した知らせだけを処理します。
Webhook の受け口は何を返せばよいですか?
受け取れたら早く 2xx を返し、重い処理は後に回します(GitHub は 10 秒以内)。本物だが使わない知らせに 4xx を返し続けると、送り手が Webhook を止める事があります。当社はテストの知らせへの 401 が 20 本続いて止められ、合言葉が合う物は 200 で受けて捨てる形に直しました(社の実測 2026-10-21)。
Webhook のテストはどうすればよいですか?
正しい鍵の署名つきの知らせと、別の鍵・署名なしの知らせの両方を撃ち、返った状態コードと、その後の処理の結果まで確かめます。当社は LINE の知らせを本番の受け口へ自分で作って撃ち、5 本とも 200 と BOT の返事を確かめました(社の実測 2026-10-24)。
出典
- GitHub Docs「About webhooks」 https://docs.github.com/en/webhooks/about-webhooks(2026-11-09 に確認)
- GitHub Docs「Validating webhook deliveries」 https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries(2026-11-09 に確認)
- GitHub Docs「Best practices for using webhooks」 https://docs.github.com/en/webhooks/using-webhooks/best-practices-for-using-webhooks(2026-11-09 に確認)
- RFC 2104「HMAC: Keyed-Hashing for Message Authentication」 https://www.rfc-editor.org/rfc/rfc2104(2026-11-09 に確認)
- Stripe Docs「Webhook エンドポイントを管理する」 https://docs.stripe.com/events/manage-webhook-endpoints(2026-11-09 に確認)
- Meta for Developers「Webhooks: Getting Started」 https://developers.facebook.com/docs/graph-api/webhooks/getting-started(2026-11-09 に確認)
- LINE Developers「Verifying webhook signatures」 https://developers.line.biz/en/docs/messaging-api/verify-webhook-signature/(2026-11-09 に確認)
- Google Cloud「Cloud Run の課金の設定」 https://docs.cloud.google.com/run/docs/configuring/billing-settings(2026-11-09 に確認)
- 社の実測 2026-08-28(verify token がログに平文で出た)・2026-09-28(受信箱方式の試しの知らせ 2 本)・2026-10-20(再送の重複 0)・2026-10-21(テストの知らせへの 401 と自動の停止、直し方の確かめ、停止の見張り)・2026-10-24(LINE の署名つきの知らせのテスト)・2026-11-08(Meta の署名の確かめ)/社の決め 2026-09-28(受信箱方式)・2026-10-07(会社ごとの合言葉と 401 の 1 本の道)
ブルーランプ 編集部/更新日 2026-11-09