Webhookとは？APIとの違い・仕組み・活用例を徹底解説

Webhook（ウェブフック）は、あるシステムで発生したイベントを別のシステムへ自動的に通知する仕組みです。APIのように定期的なリクエストを送る必要がなく、たとえば支払い完了、新規注文、配送状況の変更など、データが発生した瞬間にアプリケーションが即座に受信できます。

Webhookとは？どんな場面で活用されるのか

Webhookの基本的な仕組み

APIとWebhookの違いは「通知のタイミング」にあります。APIではアプリケーションがサーバーに「新しいデータがあるか？」と何度も問い合わせます。一方、Webhookでは受信側があらかじめ通知用のURL（エンドポイント）をサービスに登録し、イベントが発生した際にサービス側から自動的にリクエストが送信されます。

たとえば、オンラインストアが決済システムに対して定期的に「支払いが完了したか？」とAPIで確認する必要はありません。決済サービスがWebhookで「支払い完了」をすぐに通知できます。

このようにWebhookは、プログラム間の通知に特化した仕組みです。システムは常に状態を監視するのではなく、必要なイベントが発生した時だけ通知を受け取ります。

Webhookが解決する課題

Webhookは、他のサービスでの変化に素早く反応したいときに活躍します。代表的な利用例は以下の通りです：

• 決済システムが店舗に支払い成功を通知
• CRMがウェブサイトからの新規リードを受信
• 配送サービスが注文状況の更新を送信
• Gitプラットフォームが新しいコードのアップロード後に自動ビルドを開始
• メッセンジャーが新着メッセージをボットへ転送
• クラウドサービスがファイル処理の完了を連絡

こうしたシナリオのポイントは、アクションがイベントによってトリガーされることです。定期的なチェックの必要がなく、実際に変化があった時だけ通知が届きます。

このイベント駆動型の考え方は、より大規模なシステムでも活用されています。詳しくは「なぜイベントドリブンアーキテクチャがシステムを高速化・柔軟化するのか」をご覧ください。

Webhookは自動化に最適です。通知を受け取ったプログラムは、注文ステータスの変更やユーザーへの通知、データベースへの書き込み、他プロセスの起動などを自律的に実行できます。

Webhookの仕組み

イベント・URL・HTTPリクエスト

Webhookを利用するには、受信側がパブリックなURL（エンドポイント）を用意します。外部サービスはこのURL宛てにイベント発生時の通知をHTTPリクエストで送信します。

基本的な流れは以下の通りです：

• イベント発生
• サービスがデータを生成
• HTTPリクエストを送信
• 受信システムが内容を処理

たとえば、ユーザーが注文を支払うと、決済サービスが成功を検知し、オンラインストアのWebhook URLへHTTPリクエストを送ります。店舗側はこれを受信し、注文ステータスを「支払済」に変更、次の処理につなげられます。

多くの場合、HTTPのPOSTメソッドが使われ、イベント情報はリクエストボディに含まれます。しかし、サービスによっては他のメソッドを採用する場合もあります。

Webhookリクエストの内容

Webhookリクエストは一般的に以下の要素で構成されます：

• URL：受信エンドポイント
• HTTPヘッダー：認証情報などの付加データ
• リクエストボディ：イベントの主な情報（多くはJSON形式）

例えば、支払い通知の場合：

{
  "event": "payment.success",
  "order_id": "A1024",
  "status": "paid"
}

アプリケーションはeventフィールドからタイプを特定し、必要な処理を実行します。支払いなら注文を「支払済」に、配送ならステータスを更新します。

処理後、Webhookサーバーは通常HTTP 200台のステータスコードを返します。エラー応答や無応答の場合、送信側サービスは再配信を試みることがあります。

Webhookの実例

オンラインストアが外部決済システムと連携しているケースを考えましょう。購入者が注文し、決済を済ませると：

• 決済サービスが銀行から承認を受け取る
• Webhookで店舗に「支払い成功」を通知
• 店舗側が注文ステータスを自動で「支払済」に変更、レシートや倉庫への通知など後続処理へ

この仕組みは、イベントが数秒後や数時間後に発生するようなプロセスでも有効です。アプリはその間、状態を頻繁に確認する必要がなく、Webhookの通知を待つだけで済みます。

WebhookとAPIの違い

APIはリクエスト駆動、Webhookはイベント駆動

WebhookとAPIの最大の違いはデータ交換の主導者です。APIはアプリケーション側がリクエストを送って必要な情報を取得します。Webhookは受信側があらかじめURLを登録し、イベント時にサービス側から自動でリクエストが届きます。

• API：変化があったか「問い合わせる」モデル
• Webhook：変化があったら「通知を受け取る」モデル

技術文書ではpullモデル（API）とpushモデル（Webhook）と呼ばれることもあります。

WebhookとREST APIの比較

たとえば、APIで支払い情報を取得する一方、Webhookでは決済完了を即座に通知してもらう、といった使い分けが可能です。

したがって、WebhookとAPIは相互排他的な技術ではありません。

WebhookはAPIの代替ではない

実際には、WebhookとAPIは併用されるケースがほとんどです。APIは任意のタイミングでデータを取得・変更したい時に、Webhookはイベント発生時に即座に情報を得たい時に使います。

例えばCRMシステムでは、APIで顧客データの取得や更新、履歴確認ができます。Webhookは新規顧客や商談ステージ変更時に外部通知を行います。

また、Webhookで送られるのは最小限の情報（オブジェクトIDやイベントタイプ）のみの場合も多く、詳細データはAPIで取得する運用が一般的です。

WebhookとAPI、どちらを使うべきか？

Webhookが適しているケース

Webhookはイベント発生直後にシステムへ通知したい場合に最適です。主な例：

• 支払いの完了通知
• 新規注文の受信
• 配送ステータスの更新
• CRMで新しいリードが追加された時
• ファイルのアップロードや新しいコードの公開

APIによる定期的な確認はサーバーへの負担が大きく、同じ結果を何度も受け取ることも多いため、Webhookの方が効率的です。

APIが適しているケース

APIは好きなタイミングでデータを取得・操作したい場合に適しています。たとえば、ユーザーがストアの注文履歴を閲覧したいとき、アプリケーションがAPIへリクエストし、最新情報を取得します。

APIが必要となる主なシナリオ：

• 検索機能
• リスト取得
• データの新規作成・更新・削除
• ID指定で詳細情報の取得
• 任意タイミングでのサーバーアクセス

Webhookはイベント通知専用で、任意の情報取得には適しません。多くのシステムではWebhookで「変化」を受け取り、その後APIで詳細データを取りに行く組み合わせが一般的です。

Webhook、Polling、WebSocketの違い

Webhookだけでなく、PollingやWebSocketによる通知手法も存在します。

• Polling：数秒ごとなど定期的にAPIへリクエストし、新着データ有無を確認。実装が簡単ですが、無駄なリクエストが増えやすいです。
• Webhook：イベント発生時のみHTTPリクエストが送信されるため、効率的かつサーバー負荷が低いです。
• WebSocket：クライアントとサーバー間で常時双方向通信を維持。チャットやオンラインゲーム、リアルタイム取引所など、瞬時の連続データ交換が必要な場合に適しています。

WebSocketの詳細は「WebSocketとは？リアルタイム通信技術の仕組みと活用例」も参考にしてください。

用途によって選択肢は異なります。任意タイミングのデータ取得ならAPI、イベントベースの通知ならWebhook、継続的なリアルタイム通信ならWebSocketが向いています。

Webhook導入時のポイント

Webhookエンドポイントの作成

Webhookを受け取るため、インターネット上からアクセス可能なURL（エンドポイント）が必要です。開発者は受信・検証・処理用のハンドラを実装し、そのURLを外部サービスの設定画面に登録します。

例：

https://example.com/webhooks/payment

イベント発生時、サービスはこのエンドポイントに通知を送信します。HTTPS対応は必須です。ローカル開発ではトンネルサービスなどで一時的なパブリックURLを発行するケースもあります。

Webhookの認証とセキュリティ

Webhookエンドポイントは外部からのリクエストを受け入れるため、認証が重要です。アドレスが漏洩すると、第三者が偽イベントを送るリスクもあります。

多くのサービスはシークレットキーによる署名を利用し、受信側で署名検証を行います。これにより、送信元が正当なサービスかつデータ未改ざんであることを確認できます。加えて、HTTPS通信やIPアドレス制限、シークレットトークンなども有効です。

再送信と重複イベントへの対応

Webhookは一度で確実に届くとは限りません。サーバーの一時的な停止や処理遅延などで失敗した場合、サービス側は再送信（リトライ）を行います。

このため、同じイベントが複数回届くこともあり得ます。アプリケーション側は重複検知（通常はイベントIDによる）を行い、二重処理を防止しましょう。特に決済通知などでは、重複処理による二重課金や誤送信を避けるため、冪等性（idempotency）の確保が重要です。

ログ・ステータスコードの管理

Webhook受信後は、HTTP 200系のステータスコードで正常処理を通知します。エラーの場合、外部サービスは「未配信」と判断し再送信します。

また、Webhookエンドポイントで重い処理を直接行うのではなく、受信時は最低限の検証と応答のみ行い、詳細な処理は非同期で実施する設計も推奨されます。

イベントの到着時間や内容、ID、結果などを適切にログへ記録しておくと、障害時の原因特定やリトライ判定に役立ちます。

まとめ

Webhookは、システム間でイベント発生時に即時通知を自動化できる技術です。APIによるポーリングの手間を省き、決済や通知、サービス連携、業務自動化など多様な用途で活用されています。

WebhookとAPIの違いは通信の主導権にあり、APIはクライアント主導、Webhookはサービス側からの通知という役割分担です。両者は相互補完的に使われることが多く、それぞれの特性を活かした設計が推奨されます。

データ取得・操作にはAPI、イベントベースの即時反応にはWebhook、リアルタイムな双方向通信にはWebSocketが最適です。

Webhook導入時は、セキュリティ（署名検証）、再送信・重複対策、エラー処理や堅牢なログ管理など、信頼性を向上させる工夫が不可欠です。これらを適切に設計することで、Webhookはサービス間連携の強力な基盤となります。