Webhook を使うときの前提
Webhook は「変化があったときに向こうから通知が来る」仕組みで、定期的に問い合わせる（ポーリング）より効率的だ。ただし受け取る側の実装責任が大きい点が API と決定的に違う。
実装で必ず要る3点
署名検証・冪等性・即時応答は省略できません
署名検証: 受信エンドポイントは公開されるため、検証しないと第三者が通知を偽装できます。決済系では致命的です。
冪等性: 配信は再試行されるため同じ通知が複数回届きます。イベント ID で処理済みを判定しないと、二重に処理します。
即時応答: 重い処理をしてから応答すると、タイムアウトして再送を招きます。まず受領を返し、処理は非同期に回してください。
取りこぼしを前提にする
受信サーバーが停止していた時間帯の通知は、再送で届く場合もあれば失われる場合もある。Webhook だけに依存せず、定期的に API で状態を突き合わせる仕組みを併用すると、欠損に気づける。重要な処理ほどこの二重化が要る。
順序は保証されない
通知が発生順に届くとは限らない。「更新」が「作成」より先に届くこともある。イベントに含まれるタイムスタンプや状態を見て判断し、到着順を前提にした処理は書かないほうがよい。
開発時の受け取り方
Webhook はローカル環境に外部から届かないため、検証にはトンネリングツールや、提供元が用意する CLI を使う。異常系（失敗、返金、期限切れ）を手動で発火できる仕組みがあるサービスなら、本番前にひととおり確認しておきたい。