お店に「準備ができたら、この番号に電話してください」と連絡先を預けておけば、こちらから何度も「まだですか」と電話しなくて済みます。Webhookは、この折り返し先をシステムどうしで預け合う仕組みです。相手のサービスで何か出来事が起きたとき、あらかじめ登録しておいた URL へ、相手のほうから HTTP で知らせてくれます。
聞きに行く代わりに知らせてもらう
変化があったかを定期的に聞きに行く方法は、ポーリングと呼ばれます。何も起きていなくても聞き続けるので、無駄な問い合わせが増え、起きてから気づくまでにも間が空きます。こちらから必要なときに問い合わせる API とも、向きが逆です。Webhook なら、出来事が起きたその時に通知が飛んできます。
よく使われるのは、次のような場面です。
- 決済サービスで支払いが完了したら、自社システムへ知らせてもらう
- フォームが送信されたら、社内チャットや管理表へ自動で反映する
- Git へのコードの送信や、デプロイの完了をきっかけに、別の処理を動かす
- 外部サービスで起きた更新を、なるべく早く自分のアプリに取り込む
人が読むためのメール通知と違い、受け取るのは別のシステムです。通知をきっかけに、次の処理が自動で始まります。
その通知、本当に相手から？
通知を受け取る URL は、外部から呼ばれる前提で作ります。つまり、相手のふりをした偽の通知が届く可能性もあるということです。「支払い完了」の偽通知で商品が発送されてしまっては困ります。
多くのサービスは、通知に署名を付けたり、事前に共有した秘密の値を添えたりしています。受け取る側はそれを確かめて、送り主が本物かを判断します。
同じ通知が2回来たら？
Webhook は、必ず1回だけ届くとは限りません。相手が「届かなかったかもしれない」と判断すれば、同じ通知を送り直してきます。受け取る側は、同じ通知を2回処理しても結果が変わらないように作っておきます。支払い完了の通知で、ポイントが二重に付いたりしないように、ということです。届く順番も、出来事が起きた順とは限りません。
受け取れなかったら？
こちらのサーバーが止まっていた、処理の途中でエラーになった。そんなときに通知を取りこぼさないよう、相手の再送の仕組みを確かめ、受信の記録（ログ）を残しておきます。取りこぼしに気づいたとき、どうやって取り直すかの手順も決めておきましょう。