Webhookの基本(APIとの違い・受信URL・署名確認・再送・重複・失敗時)
要点
APIは自分から聞きに行く、Webhookは相手からイベント発生時に自サイトの受信URLへ知らせてくる。受信側は署名を確認して本物か確かめ、すぐ2xxを返し、同じ通知が再送・重複して届く前提で処理する。失敗はログに残す。
APIとの違い
| API | Webhook | |
|---|---|---|
| 向き | 自サイト → 相手に聞きに行く | 相手 → 自サイトに知らせてくる |
| タイミング | 自分が呼んだとき | イベントが起きたとき(注文・決済・予約・フォーム送信) |
| 例 | 「在庫を教えて」 | 「注文が入りました」 |
| 自分が用意するもの | 呼び出す処理 | 受信用のURL(エンドポイント) |
注文(外部のショップ・決済サービス)
↓ Webhook(POST で JSON を送ってくる)
自サイトの受信URL
↓
自サイト側の処理(通知メール、在庫更新、スプレッドシートへの記録 など)
受信側で守ること
| 項目 | 内容 |
|---|---|
| 受信URL | httpsのURL。推測されにくいパス。サービスの管理画面に登録する |
| 署名確認 | 多くのサービスはヘッダーに署名を付ける。共有シークレットで検証し、本物の送信元か確かめる。確認しないと、誰でも偽の「注文」を送れる |
| すぐ応答 | 受け取ったら短時間で 2xx を返す。重い処理は後で行う。遅いと失敗扱いで再送される |
| 再送 | 失敗(タイムアウト・500)すると相手が何度か送り直す |
| 重複 | 同じイベントが2回以上届くことがある。イベントIDを記録し、処理済みなら何もしない(二重メール・二重登録の防止) |
| 順番 | 届く順番がイベントの発生順とは限らない |
| 失敗時 | 受信・処理の失敗をログに残す。サービスの管理画面の送信履歴で再送できることが多い。定期的に取りこぼしを確認 |
| テスト | テストモード・テスト送信機能で試す。本番の受信URLにテストデータを流さない |
- シークレットは knowledge・Git・公開ファイルに書かない(認証情報(パスワード・秘密鍵・APIキー・トークン)はknowledgeに保存しない)。
- WordPress で受ける場合、プラグインや連携サービス(自動化ツール)の受信機能を使うことが多い。自作するなら署名確認と重複対策を省かない。
- 受信URLにキャッシュ・WAF・Basic認証がかかっていると届かない。