WebhookとAPIの違いをわかりやすく解説：使い分け・実装例・注意点

WebhookとAPIの違い

WebhookとAPIは、どちらもシステム同士をつなぐ仕組みです。ただし、情報の流れ方が違います。

APIは、自分のアプリが主導権を持ってデータを取得・操作する仕組みです。一方、Webhookは、外部サービス側でイベントが起きたときに、登録したURLへHTTPリクエストを送ってもらう仕組みです。

APIとは？こちらからリクエストする仕組み

APIは、アプリやサービスが外部システムの機能やデータを利用するための窓口です。Web APIでは、多くの場合HTTPを使ってリクエストを送り、JSONなどの形式でレスポンスを受け取ります。

たとえば、ECサイトで注文一覧を取得したい場合、アプリ側から次のようなリクエストを送ります。

GET https://api.example.com/orders

このとき、APIを呼ぶタイミングは自分のアプリが決めます。ユーザーが画面を開いたとき、夜間バッチで集計するとき、管理者が更新ボタンを押したときなど、必要なタイミングでデータを取りに行けます。

APIが得意なこと

• 最新のユーザー情報を取得する
• 商品一覧や注文一覧を検索する
• 新しいデータを作成する
• 既存データを更新・削除する
• AI APIにプロンプトを送って回答を受け取る

つまりAPIは、「こちらが知りたい」「こちらが操作したい」という能動的な連携に向いています。

Webhookとは？イベントが起きたら通知してもらう仕組み

Webhookは、外部サービスで何かイベントが起きたときに、自分のアプリへ自動で通知してもらう仕組みです。通知先として自分のURLを登録しておくと、相手サービスがそのURLへHTTP POSTを送ってくれます。

Stripeのドキュメントでは、決済成功、支払い失敗、不正利用の異議申し立て、定期課金の成功など、非同期イベントに対応するためにWebhookを使う例が紹介されています。GitHubでも、push、issue作成、pull request更新などのイベントにWebhookを設定できます。

たとえば、決済が完了したらStripeから次のような通知が届くイメージです。

POST https://your-service.com/webhooks/stripe
{
  "type": "payment_intent.succeeded",
  "data": {
    "object": {
      "id": "pi_xxx",
      "amount": 5000
    }
  }
}

Webhookが得意なこと

• 決済が完了したら注文ステータスを更新する
• フォーム送信があったらSlackへ通知する
• GitHubにpushされたら自動デプロイする
• ECサイトで注文が入ったら在庫システムへ連携する
• AIワークフローで処理完了後に次の処理を起動する

Webhookは、「変化が起きた瞬間に反応したい」ケースに向いています。

APIとWebhookの具体例

決済サービスの例

決済サービスでは、APIとWebhookの両方を使うことが多いです。

このように、Webhookはイベント通知、APIは詳細取得や操作に使うと整理しやすいです。

GitHub連携の例

GitHubでは、リポジトリにpushされたときやpull requestが作成されたときにWebhookで通知できます。CI/CDツールやデプロイサービスは、このWebhookをきっかけにビルドやデプロイを開始します。

一方で、リポジトリ一覧、issue一覧、pull requestの詳細、コミット情報などを取得する場合はAPIを使います。

AIアプリの例

AIアプリでも、APIとWebhookは使い分けます。OpenAI APIのようなAI APIへプロンプトを送る処理はAPIです。一方、ファイル変換が完了した、動画生成が終わった、外部サービスの処理が終わった、といった通知にはWebhookが使われます。

ポーリングとWebhookの違い

Webhookと一緒に理解しておきたいのが、ポーリングです。ポーリングとは、APIを定期的に呼び出して「変化があったか」を確認する方法です。

5分ごとにAPIを呼ぶ
↓
新しい注文があるか確認する
↓
あれば処理する
↓
また5分後に確認する

ポーリングは実装が単純ですが、無駄な通信が増えやすく、イベント発生から検知まで遅れが出ます。Webhookならイベントが起きたタイミングで通知が届くため、リアルタイム性が高く、API呼び出しも減らせます。

WebhookとAPIの使い分け

実務では、次の基準で考えると選びやすいです。

Webhook実装で必ず注意したいこと

1. 署名検証を行う

WebhookのURLは外部からアクセスされるため、誰かが偽のリクエストを送ってくる可能性があります。そのため、StripeやGitHubのようなサービスでは、署名ヘッダーを使って「本当にそのサービスから送られた通知か」を検証します。

署名検証をしないWebhookは危険です。たとえば、偽の「決済完了」通知を送られると、支払いが完了していないのに商品を提供してしまう可能性があります。

2. すぐに200系レスポンスを返す

Webhookの処理に時間がかかると、送信元サービスは失敗と判断して再送することがあります。重い処理はキューに入れ、Webhookの受信処理自体は短時間で終わらせる設計が安全です。

3. 同じイベントが複数回来ても壊れないようにする

Webhookは再送されることがあります。ネットワーク障害や一時的な500エラーがあると、同じイベントが複数回来る可能性があります。そのため、イベントIDを保存し、同じイベントを二重処理しないようにする必要があります。

4. 順番どおりに届くとは限らない

Stripeのドキュメントでも、イベントが生成順に届くことは保証されないと説明されています。たとえば、サブスクリプション作成、請求書作成、支払い成功のイベントが期待した順番で届かないことがあります。

重要な処理では、Webhookの内容だけで判断せず、APIで最新状態を取りに行く設計にすると安全です。

5. 受信ログを残す

Webhookの不具合は「通知が来ていない」のか「来たけど処理に失敗した」のかを切り分ける必要があります。受信時刻、イベントID、イベントタイプ、処理結果、HTTPステータスをログに残しておくと、トラブル対応が楽になります。

API実装で注意したいこと

1. APIキーを安全に管理する

APIキーは、外部サービスを操作できる重要な秘密情報です。フロントエンドのJavaScriptに直接書いたり、GitHubへコミットしたりしてはいけません。サーバー側の環境変数やシークレット管理機能を使います。

2. レート制限を考える

APIには、一定時間に呼び出せる回数の制限があります。必要以上に短い間隔でポーリングすると、制限に引っかかったり、料金が増えたりします。Webhookで代替できる部分はWebhookに任せると効率的です。

3. タイムアウトと再試行を設計する

外部APIは常に成功するとは限りません。ネットワーク障害、相手サービスの一時障害、タイムアウトが起きます。再試行、エラーログ、ユーザーへの表示、ジョブの再実行方法を考えておく必要があります。

4. APIレスポンスを信用しすぎない

外部APIのレスポンス形式は、バージョン変更や設定変更で変わることがあります。必要なフィールドがない場合、nullの場合、想定外のステータスの場合にも落ちないように実装しましょう。

WebhookとAPIを組み合わせる設計例

実務でおすすめなのは、WebhookとAPIを役割分担する設計です。たとえば、決済完了後にユーザーへ商品を提供する場合は次の流れになります。

1. ユーザーが決済する
2. 決済サービスで支払い完了イベントが発生する
3. 決済サービスがWebhookで自分のサーバーへ通知する
4. サーバーは署名を検証する
5. イベントIDを確認し、未処理なら処理を続ける
6. 必要に応じてAPIで決済の最新状態を取得する
7. 注文ステータスを「支払い完了」に更新する
8. ユーザーへメール送信、商品提供、Slack通知などを行う

この流れなら、Webhookのリアルタイム性とAPIの確実な状態取得を両方活かせます。

ノーコード・AI自動化でのWebhookとAPI

WebhookとAPIは、エンジニアだけのものではありません。Zapier、Make、n8n、Dify、GASなどの自動化ツールでもよく使われます。

• フォーム送信をWebhookで受け取り、Slackへ通知する
• Webhookで受け取った問い合わせ内容をAI APIへ送る
• AIの回答をNotionやGoogle SheetsへAPIで保存する
• ECサイトの注文Webhookを受けて、発送管理システムのAPIへ登録する

AI自動化では、Webhookが「処理開始のトリガー」、APIが「データ取得や処理実行の手段」になることが多いです。この違いを理解しておくと、ワークフロー設計がかなり楽になります。

関連して、OpenAI APIまわりの実装はOpenAI APIの記事一覧、AI開発全般はAIツールカテゴリも参考になります。

よくある質問

WebhookはAPIの一種ですか？

広い意味では、WebhookもHTTPを使ったシステム連携の一種です。ただし、一般的なAPIは「こちらから呼び出す」もの、Webhookは「イベント時に相手から呼び出される」ものとして区別すると理解しやすいです。

Webhookだけで全部できますか？

できないことが多いです。Webhookはイベント通知には向いていますが、過去データの検索、詳細取得、更新、再同期にはAPIが必要になります。

APIだけでWebhookの代わりになりますか？

ポーリングすれば似たことはできます。ただし、無駄なAPI呼び出しが増え、リアルタイム性も落ちます。イベント通知が必要ならWebhookのほうが自然です。

Webhook受信URLは公開して大丈夫ですか？

公開URLである必要はありますが、誰でも自由に処理を実行できる状態にしてはいけません。署名検証、HTTPS、ログ、重複対策、必要ならIP制限を組み合わせます。

まとめ：APIは取りに行く、Webhookは知らせてもらう

WebhookとAPIの違いは、通信の主導権にあります。APIは自分のアプリがリクエストし、Webhookは外部サービスがイベント発生時に通知してくれます。

一覧取得、検索、作成、更新、削除にはAPIが向いています。決済完了、注文発生、GitHub push、フォーム送信、処理完了のようなイベント通知にはWebhookが向いています。

実務では、WebhookとAPIをどちらか一方だけで考えるのではなく、Webhookで通知を受け取り、APIで最新状態を確認する設計がよく使われます。特に決済、注文、AIワークフロー、業務自動化では、この組み合わせを理解しておくと連携設計がかなり安定します。

参考情報

• Stripe Docs: Receive Stripe events in your webhook endpoint
• Stripe Docs: Webhook signatures
• GitHub Docs: Webhook events and payloads
• MDN: Request interface