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)。

出典

  1. GitHub Docs「About webhooks」 https://docs.github.com/en/webhooks/about-webhooks(2026-11-09 に確認)
  2. GitHub Docs「Validating webhook deliveries」 https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries(2026-11-09 に確認)
  3. GitHub Docs「Best practices for using webhooks」 https://docs.github.com/en/webhooks/using-webhooks/best-practices-for-using-webhooks(2026-11-09 に確認)
  4. RFC 2104「HMAC: Keyed-Hashing for Message Authentication」 https://www.rfc-editor.org/rfc/rfc2104(2026-11-09 に確認)
  5. Stripe Docs「Webhook エンドポイントを管理する」 https://docs.stripe.com/events/manage-webhook-endpoints(2026-11-09 に確認)
  6. Meta for Developers「Webhooks: Getting Started」 https://developers.facebook.com/docs/graph-api/webhooks/getting-started(2026-11-09 に確認)
  7. LINE Developers「Verifying webhook signatures」 https://developers.line.biz/en/docs/messaging-api/verify-webhook-signature/(2026-11-09 に確認)
  8. Google Cloud「Cloud Run の課金の設定」 https://docs.cloud.google.com/run/docs/configuring/billing-settings(2026-11-09 に確認)
  9. 社の実測 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