ウェブフック
Webhook
ウェブフックとは?
- 出来事の発生時にサーバーが先に通知
- '逆方向のAPI'
- リアルタイム連携に役立つ
ウェブフックを導入すると、作業の主語が変わります。ポーリング方式では、当社のサーバーが1分ごとに決済会社のAPIを呼び出し、「新しい決済はありますか」と問い合わせます。1日1,440回問い合わせても実際に拾えるのは数十件で、残りはすべて空振りの照会です。ウェブフックで動かすと、その無駄な問い合わせがなくなり、出来事の発生から処理までが分単位から秒単位に短縮されます。さらに、API呼び出し上限を圧迫していた空振りの照会がそっくりなくなるため、サーバー費用と障害箇所も同時に減ります。
導入前に確認すべき項目は署名検証・応答速度・再送・冪等処理の4つです。ほとんどのサービスはリクエストヘッダーにHMAC署名を付けて送るため、シークレットキーで照合して偽造リクエストを弾く必要があります。受け取る側は通常3〜5秒以内に200 OKを返さなければなりません。在庫の差し引きやメール送信のような重い処理はキューに入れ、先に応答を返すのが定石です。失敗すると提供側は数分から数時間の間隔で何度も再送するため、同じイベントIDが2回届いても注文は1件だけ作られるように防いでおく必要があります。
似たツールとの違いをはっきりさせておくと、設計がしやすくなります。通常のAPIは必要なときに取り出して使う窓口ですが、ウェブフックは相手が一度送って終わる通知なので、受け取った瞬間に処理できなければそのまま流れてしまいます。画面をリアルタイムで更新するのが目的なら、SSEやウェブソケットが適しています。1日に数十万件を順番に蓄積する必要があるなら、KafkaやSQSのようなメッセージキューが適しています。ウェブフックは「1日数千件規模のイベント伝達」に最も適した中間ツールです。
現場で最もよく誤解されるのは、「ウェブフックは一度だけ、送った順番どおりに届く」という思い込みです。再送やネットワーク事情によって同じ決済完了通知が2回届き、注文が2件作られて在庫が2回差し引かれるという事故が実際に起きます。社内ファイアウォールの内側に受信サーバーを置いた場合、開発環境ではうまく届いていた通知が本番では1件も届かないケースも少なくありません。ウェブフックは「時々取りこぼす通知」と前提にし、お金が絡むイベントについては1日1回の台帳照合(再照会)バッチも併せて動かして、夜間に抜けた件を拾い出す必要があります。
この用語は2007年にJeff Lindsayが提案したもので、イベントが発生すると自動的にデータを送信するWeb連携方式として、広く使われるようになりました。
仮想の事例で見てみましょう。役職員52名、年商180億ウォン(約215,262万円)規模の自社モール運営会社A社の話です。決済完了の有無を5分周期のバッチで確認していたため、注文書が物流センターへ渡るまでに平均7分かかり、「決済したのになぜ処理中なのか」というCS問い合わせが週40件ずつ届いていました。開発チーム4名が3週間かけて、決済ウェブフックへの切り替えに取り組みました。
- 開発チーム長のキム次長が最初の会議で、"5分ごとに問い合わせるのではなく、決済会社から先に知らせてもらう方式に変えましょう"とまとめ、PG会社の管理画面に受信URLを登録しました。
- バックエンド担当のイ代理がHMAC署名の照合ロジックを組み込み、テスト決済20件を実行したところ、署名が一致しない偽造リクエスト2件がそのまま遮断されることを確認しました。
- 運用2日目、同じ決済イベントが3回連続で届いて注文が重複作成されたため、イ代理がevent_idをDBのユニークキーに設定し、2回目以降は200 OKだけ返して無視するように変えました。
- 応答に6秒以上かかりタイムアウトの失敗率が4%まで上がったため、在庫の差し引きと案内メールの送信をキューに分け、受付と同時に応答するように改善しました。これにより失敗率は0.2%に下がりました。
- 切り替えから3週間後、出荷指示までの平均時間が7分から12秒に短縮され、CS問い合わせは週40件から6件に、1日8,640回だったポーリング呼び出しは0回になりました。
パク・ソリョン
金鍾赫