「Webhook vs API」は、実際には「どちらが優れているか」ではなく、「誰が通信を開始するか」を理解するためのテーマです。Stripeの支払い処理やGitHub連携を実装したことがあるなら、「WebhookもAPIの一種では？」と感じたことがあるはずです。結論から言うと、WebhookはAPIの対義語ではありません。逆方向に動作するAPI通信パターンです。
このガイドでは、通常のAPIとWebhookの違い、使い分け、実装時の考え方を整理します。統合機能を構築またはテストする場合、Apidogを使えば、通常のAPIエンドポイントとWebhookレシーバーの両方を一箇所で設計、モック、テストできます。
簡単な答え
- 通常のAPI、特にREST APIは、あなたがリクエストを送るのを待ちます。 あなたが呼び出し、相手がレスポンスを返します。
- Webhookは逆です。 プロバイダー側でイベントが発生した瞬間に、相手があなたのサーバーへHTTPリクエストを送ります。
- どちらもHTTPを使い、多くの場合JSONを送受信します。 そのためWebhookは「リバースAPI」や「プッシュAPI」と呼ばれます。
つまり、重要なのは「Webhook vs API」ではなく、プル vs プッシュです。
人々が「API」と言う時何を意味するのか
誰かが「APIを呼び出す」と言う場合、多くはREST APIのようなリクエスト-レスポンス型のインターフェースを指します。
たとえば、注文の状態を取得したい場合は次のように呼び出します。
GET /orders/123 HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_TOKEN
レスポンス例:
{
"id": "123",
"status": "paid",
"total": 5000
}
このモデルでは、データが必要なタイミングをあなたのアプリケーションが制御します。
これがプルモデルです。
APIは次のようなケースに向いています。
- ページ表示時に最新データを取得する
- 管理画面でレポートを生成する
- ユーザー操作をきっかけにデータを作成・更新する
- 明示的に外部サービスへ処理を依頼する
一方で、変更を検出するには何度も問い合わせる必要があります。リクエストとレスポンスの構造を確認したい場合は、APIリクエスト構造の理解を参照してください。
Webhookとは何か
Webhookは、ユーザー定義のHTTPコールバックです。
たとえば、次のようなURLをプロバイダーに登録します。
https://yourapp.com/webhooks/stripe
プロバイダー側でイベントが発生すると、そのプロバイダーはあなたのURLへHTTP POSTを送信します。
POST /webhooks/stripe HTTP/1.1
Host: yourapp.com
Content-Type: application/json
ペイロード例:
{
"type": "payment.succeeded",
"data": {
"payment_id": "pay_123",
"amount": 5000
}
}
この場合、あなたのアプリケーションは呼び出し側ではなく受信側です。
サーバーは待機し、イベントが発生したらプロバイダーから通知を受け取ります。
これがプッシュモデルです。
Webhookは次のような用途で使われます。
受信側の設計について詳しく知りたい場合は、Webhook APIとは何かを参照してください。
Webhook vs API: 核となる違い
| 比較項目 | 通常のAPI REST | Webhook |
|---|---|---|
| 交換を開始するのは誰か | あなた、つまりクライアント | プロバイダー |
| モデル | リクエスト-レスポンス、プル | イベント駆動、プッシュ |
| タイミング | あなたが呼び出した時 | イベントが発生した時 |
| 方向性 | あなたがプロバイダーを呼び出す | プロバイダーがあなたのエンドポイントを呼び出す |
| 最適な用途 | オンデマンドのデータ取得や操作 | 予測できないイベントへの反応 |
| 主なコスト | 変更検出にはポーリングが必要 | 公開エンドポイントのホストと保護が必要 |
最も重要なのは、誰が呼び出しを開始するかです。
この方向性の違いが、設計、セキュリティ、テスト方法の違いにつながります。
「Webhookも単なるAPIではないのか？」正直な答え
答えは、イエスでもありノーでもあります。
Webhookは、通常のAPIと同じ構成要素を使います。
- HTTP
- URL
- ヘッダー
- JSONボディ
- ステータスコード
その意味では、WebhookもAPI通信の一種です。
違いは役割です。
通常のAPIでは、あなたのアプリケーションがクライアントです。
Your app -> Provider API
Webhookでは、プロバイダーがクライアントとしてあなたのエンドポイントを呼び出します。
Provider -> Your webhook endpoint
多くのチームは、RESTエンドポイントとWebhookを同じAPI契約の一部としてドキュメント化します。OpenAPI 3.1では、Webhookを記述するためのwebhooksフィールドも追加されています。Apidogでも同じ考え方で扱えます。詳しくはOpenAPIコールバックとWebhookを参照してください。
つまり、正確には次のように表現できます。
Webhookは独立した別技術ではなく、API通信の特定パターンです。
「Webhook vs API」と言う場合、実際には「プロバイダーのリクエスト-レスポンスAPI」と「プロバイダーのイベント通知メカニズム」を比較しています。
どちらをいつ使うべきか
通常のAPIコールを使うのは、次のような場合です。
- ページ読み込み時にデータが必要
- レポート実行時に最新情報を取得したい
- 課金を作成したい
- レコードを更新したい
- メッセージを送信したい
- ユーザー操作をきっかけに処理を開始したい
例:
const response = await fetch("https://api.example.com/orders/123", {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.API_TOKEN}`
}
});
const order = await response.json();
console.log(order.status);
Webhookを使うのは、次のような場合です。
- 何かが変更された瞬間を知りたい
- イベント発生タイミングを予測できない
- 数秒ごとのポーリングが無駄になる
- プロバイダー側が処理完了タイミングを持っている
例:
import express from "express";
const app = express();
app.use(express.json());
app.post("/webhooks/payment", (req, res) => {
const event = req.body;
if (event.type === "payment.succeeded") {
console.log("支払い成功:", event.data.payment_id);
// 注文ステータスを更新する
}
res.status(200).send("ok");
});
app.listen(3000, () => {
console.log("Webhook receiver running on port 3000");
});
もし実際の選択肢が「Webhookを使うか、定期的にAPIを確認するか」であれば、Webhook vs ポーリングも参考になります。
両者は連携し、通常そうしています
実際の統合では、APIとWebhookは競合しません。多くの場合、セットで使います。
Stripeの支払い処理を例にすると、流れは次のようになります。
- あなたのアプリがStripe APIを呼び出して支払いインテントを作成する
- Stripeがバックグラウンドで支払いを処理する
- 支払いが成功または失敗したら、StripeがあなたのWebhookエンドポイントを呼び出す
- あなたのアプリが注文ステータスを更新する
擬似コードでは次のような役割分担です。
// 1. APIで処理を開始する
await createPaymentIntent(orderId);
// 2. Webhookで結果を受け取る
app.post("/webhooks/stripe", async (req, res) => {
const event = req.body;
if (event.type === "payment_intent.succeeded") {
await markOrderAsPaid(event.data.object.metadata.order_id);
}
res.sendStatus(200);
});
APIはアクション開始に使い、Webhookは結果通知に使います。
どちらかがもう一方を完全に置き換えるわけではありません。
信頼性の高い統合では、アウトバウンドAPIとインバウンドWebhookを組み合わせるのが一般的です。より広い設計パターンについては、イベント駆動型APIを構築する方法を参照してください。
Webhook vs WebSocket vs ポーリング
混同されやすい3つの方式を整理します。
Webhook vs ポーリング
ポーリングは繰り返し問い合わせます。Webhookは通知されるのを待ちます。Webhook vs WebSocket
Webhookはイベントごとの単発HTTP POSTです。WebSocketは継続的な双方向接続です。詳しくはWebhook vs WebSocketを参照してください。Webhook vs API
主な違いは呼び出しの方向性です。通常のAPIはあなたが呼び出し、Webhookは相手があなたを呼び出します。
Apidogで両方を設計・テストする方法
Webhookの開発では、次のような問題が起きがちです。
- 実際のイベントが発生しないとテストしづらい
- ローカル環境のエンドポイントを外部から呼び出せない
- ペイロードの構造が不明確なまま実装が進む
- 署名検証やステータスコードの扱いを後回しにしやすい
Apidogを使うと、通常のAPIとWebhookを同じワークスペースで扱えます。
実装時は、次の流れで進めると整理しやすくなります。
- REST APIエンドポイントを定義する
- リクエスト、レスポンス、ステータスコードをドキュメント化する
- Webhookの受信エンドポイントを定義する
- 想定されるWebhookペイロードを作成する
- 手動POSTでWebhookハンドラーを検証する
- アサーションを追加してレスポンスや処理結果を確認する
- OpenAPI契約としてREST APIとWebhookをまとめて管理する
Webhookレシーバーは、通常のAPIエンドポイントと同じように契約を明確にしてから実装するのが安全です。
たとえば、Webhookの入力仕様を先に決めます。
{
"type": "payment.succeeded",
"data": {
"payment_id": "pay_123",
"order_id": "order_456",
"amount": 5000
}
}
その後、受信側で次を検証します。
- 必須フィールドが存在するか
- イベントタイプが想定内か
- 同じイベントが複数回来ても安全か
- 正しいHTTPステータスコードを返すか
- 署名検証を通過したリクエストだけ処理するか
設計、モック、テスト、ドキュメント作成を一つのワークスペースで行えるため、Webhookレシーバーも他のAPI契約と同じように扱えます。Apidogをダウンロードして、APIとWebhookを一箇所で構築・テストできます。
よくある質問 FAQ
WebhookはAPIですか？
WebhookはAPI通信のパターンです。独立した別技術ではありません。HTTP、URL、ヘッダー、JSONペイロードを使う点は通常のAPIコールと同じです。
違いは、あなたがプロバイダーを呼び出すのではなく、プロバイダーがあなたのエンドポイントを呼び出す点です。そのため、WebhookはリバースAPIと呼ばれることがあります。
APIなしでWebhookを使用できますか？
単独で使うことは少ないです。
多くのワークフローでは、最初にプロバイダーのAPIを呼び出して処理を開始し、その後の結果をWebhookで受け取ります。両者は補完関係にあります。
受信側の構築方法については、Webhook APIとは何かを参照してください。
WebhookはAPIより高速ですか？
イベントへの反応という意味では、Webhookの方が適している場合があります。
ポーリングでは次のチェックまで待つ必要がありますが、Webhookではイベント発生時に通知されます。ただし、オンデマンドでデータを取得したい場合は、直接APIコールを使うべきです。
WebhookはREST APIを置き換えますか？
置き換えません。
REST APIはオンデマンドのリクエストやアクションに向いています。Webhookはリアルタイムのイベント通知に向いています。本番システムでは、通常どちらも使います。
Webhookは安全ですか？
Webhookは公開エンドポイントを持つため、セキュリティ対策が必要です。
一般的には、プロバイダーが送信する署名を検証し、正規のリクエストだけ処理します。詳しくはWebhook署名検証を参照してください。
結論
「Webhook vs API」は正確な比較ではありません。
通常のAPIは、あなたが必要なタイミングで呼び出すプル型の通信です。Webhookは、プロバイダー側でイベントが発生した時に通知を受けるプッシュ型の通信です。
判断基準はシンプルです。
- タイミングをあなたが制御するならAPI
- タイミングをプロバイダーが制御するならWebhook
- 実際の統合では、多くの場合その両方を使う
どちら側を構築する場合でも、ApidogでエンドポイントとWebhookレシーバーを一緒に設計、モック、テストできます。
Top comments (0)