LASSIC Media らしくメディア

「外部サービスと連携する開発で、ベンダーから『Webhookで受け取ります』という説明を受けた。なんとなくデータが届く仕組みらしいが、APIと何が違うのか、運用で何に気をつければよいのかがつかめない」——IT事業部で外部サービス連携やSaaS導入の提案を確認する立場にいると、こうした場面に行き当たることがあるのではないでしょうか。Webhookは、決済や申込、チャットツールの通知など、さまざまな連携の裏側で使われている一般的な仕組みですが、画面に現れるものではないため、発注者やPMにとってはイメージしづらい領域になりがちでしょう。しかし、その挙動を大まかにでも理解しておくと、連携の信頼性や障害時の切り分け、セキュリティの検討といった、実務に直結する論点を判断しやすくなります。本記事では、特定サービスの設定手順ではなく、Webhookとはそもそも何を指すのか、よく比較されるポーリングとの違い、そして導入・運用で押さえておきたい観点を、発注者の視点から順に整理していきます。専門用語をすべて覚える必要はありませんが、「どういうときにデータが飛んでくるのか」という粒度で理解できていれば、ベンダーとの会話の解像度は変わってくるはずです。

Webhookとは何か

Webhookとは、あるシステムで特定のイベントが起きたときに、その情報をリアルタイムで別のシステムへ自動的に通知する仕組みです。たとえば決済サービスで「入金が完了した」、フォームで「申込が登録された」といった出来事が発生した瞬間に、あらかじめ登録しておいた受信先のURLへ、HTTPのPOSTでデータが送られます。受け取った側は、その通知をきっかけに自分の処理（帳票の作成、担当者への連絡、在庫の更新など）を動かせるわけです。

身近なたとえで言えば、宅配便の「配達完了通知」に近いものと考えると分かりやすいでしょう。荷物が届いたかどうかを自分で何度も確認しに行かなくても、届いた瞬間に相手から知らせが来ます。Webhookも同じで、イベントが起きた「その時」に送信元のほうから通知が届くため、受信側が「もう起きたかな」と繰り返し問い合わせずに済むのです。この「起きたら教えてくれる」という向きが、Webhookの性格を理解する鍵になります。

Webhookは、しばしば「逆向きのAPI」と表現されることもあります。通常のAPI呼び出しでは、情報が欲しい側が相手に問い合わせて取りに行くのが基本です。一方Webhookでは、情報を持っている側が、変化が起きたタイミングで相手に送りつけます。データの流れる向きが逆になっている、と捉えると整理しやすいでしょう。次の図は、イベントの発生元から受信側サーバへ通知が送られる流れを、単純化して示したものです。

ポーリングとの違い

Webhookと対比される仕組みに、ポーリングがあります。ポーリングとは、受信したい側が「何か変化はありましたか」と、相手に一定間隔で問い合わせ続ける方式です。両者は目的が近いものの、通信の向きと効率に違いがあります。代表的な違いを表に整理しました。

どちらが適しているかは、連携の性質によって変わります。変化がすぐ反映されてほしい連携ではWebhookが向きますし、送信元がWebhookに対応していない場合や、まとめて定期的に取り込めば足りる連携では、ポーリングのほうが素直なこともあるでしょう。両者を組み合わせ、通常はWebhookで受け取りつつ、取りこぼしに備えて定期的なポーリングで補う、という設計が採られることもあります。どちらか一方が常に優れているという話ではない、という点は押さえておきたいところです。

Webhookが使われる場面は、身の回りのシステム連携に数多くあります。たとえば決済サービスからの入金完了通知を受けて社内の売上計上や出荷指示を動かす、問い合わせフォームの送信を受けてチャットツールへ即時に知らせる、コード管理サービスへの反映をきっかけにビルドやテストを自動で走らせる、といった連携はいずれもWebhookが土台になっていることが多いものです。共通しているのは、「相手側で何かが起きたら、それを合図にこちら側の処理を始めたい」という要件があるという点でしょう。逆に、大量のデータをまとめて夜間に取り込むような処理では、必ずしもWebhookが最適とは限りません。自社のどの業務で「起きたらすぐ動きたいのか」を洗い出しておくと、連携方式の議論がかみ合いやすくなります。

Webhookの一般的な流れ

Webhookを使った連携は、大まかに次のような段取りで動きます。細部はサービスによって異なりますが、全体像をつかんでおくと、提案書の記述を読み解く助けになるでしょう。

• 受信側が、通知を受け取るためのURL（エンドポイント）を用意し、送信元のサービスに登録する。
• 送信元で対象のイベント（入金完了、申込登録など）が発生する。
• 送信元が、登録されたURLへイベントの情報をHTTP POSTで送信する。
• 受信側がデータを受け取り、内容を確認したうえで自分の処理を実行する。
• 受信側が「正常に受け取った」ことを示す応答（HTTPステータス200など）を返す。

この段取りのうち、発注者として意識しておきたいのは、受信側に「外部から通知を受け取る窓口」を設ける必要があるという点です。ポーリングであれば受信側は自分から取りに行くだけで済みますが、Webhookでは外部に開かれた受け口を用意し、それを守る備えも求められます。ここが、次に述べる運用上の観点につながっていきます。

導入・運用で意識したい観点

Webhookは仕組み自体はシンプルですが、実運用で安定させるにはいくつか押さえておきたい観点があります。発注や運用の意思決定に関わる立場からは、次の5つを確認しておくと判断がしやすくなるでしょう。

受信エンドポイントのセキュリティ（署名検証）

Webhookの受け口は外部に公開されるため、送信元を装った偽の通知が送られてくる可能性を想定しておく必要があります。これに備えて、多くのサービスは通知に署名（あらかじめ共有した秘密の値をもとに計算したデータ）を付けて送ります。受信側でこの署名を検証し、正規の送信元から届いたものかを確かめてから処理する、という手順が基本です。署名検証を省いてしまうと、外部から不正なデータを送り込まれる余地を残すことになりかねません。提案された設計で、この検証が組み込まれているかは確認しておきたいポイントでしょう。

冪等性（同じ通知が複数回届く前提）

Webhookでは、通信の行き違いなどにより、同じイベントの通知が複数回届くことがあります。このとき、受け取るたびに処理を繰り返してしまうと、たとえば同じ入金を二重に計上するといった不具合につながりかねません。そこで、同じ通知を何度受け取っても結果が変わらないように処理を設計しておく考え方が大切です。これを冪等性と呼びます。通知に含まれる一意のIDを記録しておき、すでに処理済みのものはスキップする、といった作り込みが代表例といえるでしょう。重複配信は起こり得るものとして設計する、という前提を共有しておくとよいでしょう。

再送とタイムアウトへの備え

受信側が一時的に停止していたり、応答が遅れたりすると、送信元は通知を届けられません。多くのサービスは、こうした場合に時間を空けて何度か再送する仕組みを持っているのが通例です。受信側としては、処理に時間がかかる場合はいったん通知を受け取って素早く応答だけ返し、重い処理は後ろで非同期に進める、という設計が採られることもあります。応答が遅れると送信元がタイムアウトと判断し、不要な再送を招くことがあるためです。再送の回数や間隔は送信元の仕様によるため、連携先ごとに確認しておくと運用の見通しが立てやすくなります。

監視とログ

Webhookは裏側で自動的に動くため、うまく届かなかったときに気づきにくいという難点があります。受信のログを残し、届いた通知の件数や処理の成否を把握できるようにしておくと、障害の予兆や取りこぼしに気づきやすくなるでしょう。ログが無いまま運用していると、「連携が止まっていたことに後から気づく」といった事態を招きかねません。どこまでを記録し、異常時にどう検知するのかは、運用設計の段階で整理しておきたい論点です。

取りこぼしへの補完策

Webhookはリアルタイム性に優れる一方、送信元・受信側・通信経路のいずれかに問題があれば、通知が届かないこともあり得ます。重要なデータの連携では、Webhookだけに頼らず、定期的にポーリングで差分を取り込んで補完する、といった二重の備えが検討されることもあります。どこまでの確実性が求められるかは連携の重要度によって変わるため、要件に応じて補完策の要否を判断するとよいでしょう。

ここまでの5つの観点は、互いに関係し合っています。たとえば再送に備えることは、結果として同じ通知が複数回届く場面を増やすため、冪等性の設計とセットで考える必要があります。発注側としては、この5つをチェックリストのように持っておき、連携の提案を受けるたびに照らし合わせる進め方が現実的でしょう。

導入時の注意点

Webhookの導入で見落とされやすいのが、「受け取って終わり」ではないという点です。外部に受け口を開く以上、セキュリティの担保、重複や取りこぼしへの備え、届かなかったときの検知までを含めて、はじめて安定した連携になります。逆に、これらを軽視したまま「とりあえず通知を受け取る」だけの作りにしてしまうと、データの二重計上や取りこぼしといった、業務に影響する不具合を抱え込むことにもなりかねません。なお本記事は、特定サービスのWebhook設定手順を解説するものではなく、Webhookという仕組みの考え方と、導入・運用で押さえたい観点に焦点を当てているものです。個別サービスの細かな設定を詰める段階では、公式ドキュメントや連携実績のあるベンダーへの確認が別途必要になるでしょう。

リクエストの流れで見る具体イメージ

Webhookの働きは、通知が届いてからの流れに沿って追うとつかみやすくなります。決済完了をきっかけに社内システムが動く場合の一例を、簡略化して挙げてみましょう。

決済サービスで 入金が完了する
  → 決済サービスが 登録済みURLへ HTTP POSTで通知する
  → 受信側が 署名を検証して 正規の通知か確認する
  → 通知IDを確認し 処理済みでなければ 帳票作成や担当者連絡を実行する
  → 受信側が ステータス200を返す
      （応答が遅れると 決済サービスは後で再送する場合がある）

この流れの中で、受信側は「検証する」「重複を避ける」「素早く応答する」という3つの役割を担っていることが読み取れます。単に通知を受け取るだけでなく、その前後に備えがあってはじめて、連携が安定して回るわけです。障害が起きたときも、どの段階で止まっているのか——通知が届いていないのか、検証で弾かれているのか、処理でつまずいているのか——を切り分ける手がかりとして、この流れは役立つはずです。

まとめ

• Webhookとは、イベント発生時に送信元から受信側へHTTP POSTで自動通知する仕組みで、「起きたら教えてくれる」という向きが特徴です。
• 受信側が問い合わせ続けるポーリングと違い、無駄な通信を抑えつつリアルタイムに近い連携を実現しやすくなります。
• 受信側には、外部から通知を受け取る公開エンドポイントを設ける必要があり、それを守る備えも求められます。
• 運用では、署名検証によるセキュリティ、重複配信に備えた冪等性、再送・タイムアウトへの対応、監視とログ、取りこぼしの補完といった観点が要点になります。
• 本記事は特定サービスの設定手順ではなく、Webhookという仕組みの考え方と、導入・運用で押さえたい観点の整理を狙いとしています。

よくある質問

著者：テレリモ総研編集部　鈴木 亮佑

ご不明な点はお問い合わせフォームからもご連絡いただけます。

出典

• MDN Web Docs「Web API の紹介」
• GitHub Docs「Webhook について」
• Stripe「Webhooks」

Tweet