- APIに聞きに行く方法と、Webhookで知らせてもらう方法の違い
- フォーム送信や入金の通知が届くまでの流れ
- 受け取る側で確かめる送り元・署名・再送と、止まったときの気づき方
結論
Webhook（ウェブフック）は、あるサービスで何かが起きたときに、決めておいたURLへ向こうから知らせを送ってもらう仕組みです。APIを使って「新しいことはある？」とこちらから聞きに行く方法とは、やりとりを始める側が逆になります。便利な反面、受け取る側は「本物の知らせか」「届かなかったときにどう気づくか」を自分で用意する必要があります。
聞きに行くか、知らせてもらうか
APIは、プログラムが別のサービスの機能やデータを決まった手順で使うための窓口です。APIで新しい注文を知るには、数分おきに問い合わせを繰り返すことになります。これを「ポーリング」と呼びます。
| 見るところ | ポーリング（API） | Webhook |
|---|---|---|
| 始める側 | 受け取りたい側 | 出来事が起きた側 |
| 届く早さ | 問い合わせの間隔しだい | 起きたらすぐ |
| 向いている場面 | たまに確かめる、対象が少ない | 出来事をすぐ知りたい、対象が多い |
例えばGitHub（ソフト開発で使われるサービス）の公式ドキュメントでも、見張る対象が多いとポーリングはAPIの回数制限を使い切りやすく、たまにしか確かめない場合や対象が少ない場合には向く、と説明されています。
問い合わせの間隔しだいで、知るのが遅れます。
受け取る側は、送り元の確認と、止まったことに気づく仕組みを用意します。
身近な例で流れを見る
架空の例として、問い合わせフォームに送信があったら社内のチャットに通知する連携を考えます。
- フォームのサービスに、知らせを受け取るURLを登録する
- 誰かがフォームを送信する
- フォームのサービスが、そのURLへ送信内容をHTTPで送る
- 受け取った側が内容を読み、チャットに投稿する
入金があったら会計の仕組みに知らせる、という連携も同じ形です。
受け取る側で気をつけること
知らせを受け取るURLは、外から届く場所にあります。誰でも偽の知らせを送れるため、送り元を確かめる仕組みが要ります。GitHubのドキュメントでは、次のような扱いが案内されています。ほかのサービスでは方法が違うので、使うサービスの公式の説明で確かめてください。
- 合言葉（シークレット）を決め、知らせごとの署名で本物かを確かめる。合言葉をURLに入れない
- HTTPSで受け取る
- 10秒以内に受け取ったと返事をし、重い処理は後で行う
- 失敗した知らせは自動では送り直されず、過去3日分を手動で送り直せる
送り直しなどで同じ知らせが2回届くこともあるため、二重に処理しない作りにしておきます。
止まったことに気づくには
Webhookは、届かなくても何も起きないので、止まったことに気づきにくい仕組みです。受け取った知らせと失敗を記録するログを残し、ときどきAPIで一覧を取って、抜けがないか照らし合わせます。通知先のチャットや担当者が替わったときに、登録したURLを直し忘れることもあります。
まとめ
確認リスト
- どのサービスから、どのURLへ知らせが届く設定かを書き出したか
- 送り元を署名などで確かめているか
- 合言葉をURLに入れていないか
- 同じ知らせが2回届いても困らない作りか
- 届かなかったときに気づける記録や確認の手順があるか
今日、まず確認すること
使っているサービスで、何かが起きたときの通知がどこへ届く設定になっているかを確かめてください。