Webhookとは|APIとの違いと、通知が届く仕組み・安全に受け取る注意点

結論: **Webhook(ウェブフック)**は、「何かが起きたら、このURLに知らせて」と、先にお願いしておく仕組みです。サービス側が、イベントの発生時に、自動で、HTTPで通知を送ります。問い合わせに行くAPIとは、向きが逆で、無駄な問い合わせが少なく、反応も早いのが、利点です。ただし、受け取る側の備え(署名の検証、再送への対応)が、欠かせません。

Webhookとは

たとえば、次のような場面で使われています。

• **決済サービス:**支払いが完了したら、ショップのシステムに、通知する
• **GitHub:**コードが更新されたら、自動でテストやデプロイを始める
• **チャットツール:**特定の投稿があったら、別のシステムに、知らせる
• **フォーム:**回答が送信されたら、スプレッドシートに、記録する

「起きた時だけ、向こうから届く」のが、特徴です。

ポーリングとの違い

APIとの違い

**対立するものではなく、組み合わせて使います。**たとえば、Webhookで「注文が入った」と知らされたら、APIで、詳しい注文内容を取りに行く、といった形です。APIの基本は、APIとはで解説しています。

通知が届く流れ

1. 受け取るURLを、サービスに登録する
2. 出来事が起きる(決済完了、投稿など)
3. サービスが、そのURLへ、HTTPリクエスト(多くはPOST)で通知を送る
4. 受け取る側が処理し、「200」などの成功の応答を返す

通知の中身は、JSONという形式で、届くことが多くあります(JSONとは)。

受け取る側が気をつけること

① 本物かどうかを、署名で確認する

受け取るURLは、外部から、誰でも送れる入口になります。偽の通知を防ぐために、多くのサービスは、署名を付けます。

• サービスと、受け取る側が、共通の秘密の文字列を持つ
• 通知に付いた署名を、受け取る側も、同じ秘密で計算して、一致するか確認する
• 秘密の文字列は、コードに直書きしない(環境変数とは)

② すぐに「200」を返す

応答が遅いと、サービス側が、失敗とみなして、再送します。重い処理は、受け取ったあとに、別の仕組み(キューなど)で行い、まず、「200」を返します。

③ 同じ通知が、複数回届いても、大丈夫にする

再送や、通信の都合で、同じ通知が、複数回届くことがあります。通知のIDを記録して、処理済みなら、何もしない作りにします。この性質を、冪等性といいます(冪等性とは)。

④ HTTPSで受け取る

通知には、顧客の情報などが含まれることがあります。HTTPSで受け取ります。

よくあるトラブル

まとめ

• Webhookは、何かが起きた時に、向こうから、登録したURLへ通知が届く仕組み
• APIは取りに行く、Webhookは届く。ポーリングより、無駄がなく、反応が早い
• 受け取る側は、署名の検証・すぐに200を返す・冪等性・HTTPSが大切
• 秘密の文字列は、環境変数で管理する

関連記事:APIとは、JSONとは、冪等性とは、APIキーとは、環境変数とは