ピクセル菌
ログをまとめています。
706 文字
4 分
Webhooksは「向こうから叩かれるAPI」
Webhooks は、「何かが起きたら、あなたが指定した URL に対して HTTP で POST しますよ」という連携方式です。普段の API が「こちらから叩く」のに対して、Webhooks は 向こうから叩かれる API、と捉えると分かりやすいです。
ポーリングとの対比
外部サービスのイベントを知りたいときに、ポーリング（定期的に問い合わせる）と Webhooks（イベント時にプッシュしてもらう）が選択肢になります。
- ポーリング：シンプル。ただし、頻度を上げるとコスト・負荷が増え、下げるとリアルタイム性が落ちる。
- Webhooks：イベント時にだけ通信が走るので効率的。ただし、受け取り側のエンドポイントを常に動かす必要がある。
リアルタイム性とコスト効率を両立しやすいのが Webhooks です。
よくある利用例
- Stripe：決済成功・サブスク更新・チャージバックなどを
POST /webhooks/stripeのような URL に通知。 - GitHub：push、PR、issue 更新を CI や Bot に通知。
- Slack：イベント API、スラッシュコマンド、Interactive Components の応答受け。
実装で外せないこと
署名検証
Webhooks の受け口は基本的に公開URLになります。誰でも叩ける状態なので、本当に提供元から来たリクエストか を検証しないと、なりすましのリクエストでシステムが踊らされます。
- HMAC 署名（共通秘密鍵）をヘッダーで送ってもらい、サーバー側で再計算して一致を確認するのが定番。
- リクエストボディそのままに対して署名するので、フレームワークの仕様でボディを書き換えてしまうとハマる。
冪等処理
ネットワークの都合で、同じイベントが複数回飛んでくる ことは普通にあります。
- イベントIDで「処理済みかどうか」を記録しておく。
- 二重に処理しても壊れないように、副作用部分を冪等に書く。
早く 2xx を返す
提供元は「タイムアウト＝失敗」と見なして再送してくることが多いです。重い処理を同期で走らせると、再送ループに巻き込まれます。
- まずは
200か202を返す。 - 重い処理はキューに逃がしてワーカーで処理する。
再送とリトライ
提供元の多くは、4xx/5xx を受けたら数分〜数時間おきにリトライしてくれます。完全に壊れていても、復旧後に取り戻せるように、再送可能な前提でログを残しておくと安心です。
受け取れない場面への備え
ローカル開発で公開URLが用意できない場合は、ngrok や Cloudflare Tunnel のようなトンネルツール、あるいは各サービスの開発用イベントログ／再送機能を活用すると、Webhooks の受け側の動作確認が楽になります。