APIとWebhookの使い分け｜リアルタイム連携を設計する判断基準と実装ポイント

外部サービスとWebシステムを連携するとき、

「APIとWebhookは何が違うのか」

「リアルタイム連携ならWebhookを使うべきなのか」

「APIだけでもシステム連携できるのではないか」

と迷うことがあります。

APIとWebhookはどちらもシステム連携に利用されますが、役割は異なります。

簡単に整理すると、

APIは「こちらから必要な情報を取りに行く」

Webhookは「何か起きたときに相手から知らせてもらう」

という違いがあります。

例えば決済サービスと連携する場合、

自社システム
↓
API
↓
決済サービス
↓
現在の契約情報を取得

という使い方があります。

一方で、

決済成功
↓
決済サービス
↓
Webhook
↓
自社システムへ通知

という使い方もあります。

実際のシステム開発では、

APIかWebhookのどちらか一方を選ぶのではなく、両方を組み合わせるケースが多くあります。

例えば、

Webhook
↓
「契約が変更された」と通知を受け取る
↓
API
↓
最新の契約情報を取得

という設計です。

この記事では、APIとWebhookの違い、使い分けの判断基準、リアルタイム連携を実装するときの再送・重複・セキュリティまで具体的に解説します。

APIとWebhookの違い

まず、それぞれの仕組みを整理します。

APIとは

APIは、システムから別のシステムへリクエストを送り、データ取得や処理を行う仕組みです。

例えば顧客管理サービスから顧客情報を取得する場合、

自社システム
↓
「顧客123の情報をください」
↓
外部API
↓
顧客情報を返す

という流れです。

つまり、自社システム側から処理を開始します。

例えば、

顧客情報取得
商品登録
決済作成
メール送信
在庫取得

などにAPIを利用します。

Webhookとは

Webhookは、外部システム側でイベントが発生したときに、指定したURLへHTTPリクエストを送ってもらう仕組みです。

例えば、

Stripeなどの決済サービス
↓
決済成功
↓
自社Webhook URLへ通知
↓
自社システムが処理

という流れです。

自社システムが何度も、

「決済されましたか？」

と確認する必要がありません。

何か起きたときに、外部サービス側から知らせてもらえます。

APIとWebhookを簡単に比較

項目	API	Webhook
通信開始	自分から	相手から
主な用途	取得・登録・更新	イベント通知
リアルタイム性	呼び出し頻度による	高い
定期確認	必要な場合あり	基本不要
データ量	必要な情報を取得可能	イベント情報中心
障害時対応	API再実行	Webhook再送・再処理

つまり、

APIは処理を要求する仕組み

Webhookはイベントを通知する仕組み

と考えると分かりやすいでしょう。

APIだけでもリアルタイム連携できる？

技術的には可能です。

例えば5秒ごとにAPIを呼び出して、

「新しい注文がありますか？」

と確認します。

これをポーリングと呼びます。

例えば、

10:00:00 API取得
10:00:05 API取得
10:00:10 API取得
10:00:15 API取得

という処理です。

注文が発生していなくてもAPIを呼び続けます。

利用者や連携対象が少なければ問題ないこともありますが、頻度を高くするとリクエスト数が増えます。

Webhookなら、

注文発生
↓
Webhook送信

となるため、変化があったときだけ通信できます。

Webhookが向いているケース

特に次のような場合はWebhookが向いています。

1．決済結果を受け取りたい

例えば、

決済開始
↓
決済サービス側で処理
↓
決済成功
↓
Webhook
↓
自社DBを更新

というケースです。

決済は、自社システムの画面操作と別のタイミングで状態が変わることがあります。

そのためWebhookとの相性がよい領域です。

2．サブスクリプションの状態変更

例えば、

契約開始
プラン変更
決済失敗
解約
契約終了

などです。

外部サービス側で状態が変わったタイミングを受信します。

3．メール送信結果

メール配信サービスを利用する場合、

メール送信
↓
配信成功
↓
開封
↓
エラー

などのイベントをWebhookで受信できる場合があります。

4．外部サービスでデータが変更された

例えばCRMで、

顧客情報変更
↓
Webhook
↓
自社システムの同期処理

という構成です。

5．GitHubなどのイベント連携

例えば、

コードPush
↓
Webhook
↓
CI処理開始

という使い方です。

何かのイベントをきっかけに別の処理を開始する場合、Webhookが適しています。

APIが向いているケース

一方、APIの方が自然なケースもあります。

1．ユーザー操作によって情報を取得する

例えば、

「顧客情報を見る」

ボタンを押したときに外部CRMから情報を取得する場合です。

ユーザー
↓
画面表示
↓
API
↓
顧客情報取得

とします。

2．データを登録・変更したい

例えば、

自社システム
↓
API
↓
外部サービスへ顧客登録

という処理です。

Webhookは基本的に通知を受ける仕組みなので、こちらから相手へ処理を依頼する場合はAPIを利用します。

3．必要なタイミングだけ最新情報を取得したい

例えば、

管理画面を開いたときだけ最新請求情報を確認する

というケースです。

リアルタイム同期が不要ならAPIだけでも十分です。

4．一括データを取得したい

例えば、

全顧客一覧
注文一覧
商品一覧

など、大きなデータセットを取得する場合です。

Webhookは通常、

「注文123が作成されました」

というイベント通知に向いています。

全データ取得はAPIが適しています。

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

実際には、この構成が非常に重要です。

例えば外部サービスで、

顧客情報が変更

された場合です。

Webhookの中に顧客情報をすべて含める方法もあります。

しかし、

Webhook
↓
CUSTOMER_UPDATED
customer_id：123

だけ受信し、

API
↓
顧客123の最新情報取得

という設計もできます。

これによりWebhookのデータ構造への依存を減らし、最新情報をAPIから取得できます。

つまり、

Webhookは「変化があったことを知る」

APIは「最新状態を取得する」

という役割分担です。

APIとWebhookの使い分けを判断する5つの質問

システム連携を設計するときは、次の質問を考えると整理しやすくなります。

1．どちらから処理を開始するのか

自社システムから開始
→ API

外部サービスのイベントから開始
→ Webhook

2．リアルタイム性は必要か

数分遅れても問題ない
→ APIによる定期取得でも可能

すぐ反映したい
→ Webhookを検討

3．データを取得したいのか、イベントを知りたいのか

詳細データ取得
→ API

イベント発生通知
→ Webhook

4．何も起きていないときも確認する必要があるか

ポーリングでは定期的にAPIを呼びます。

Webhookならイベント発生時だけ通知できます。

5．Webhookを受信できなかった場合をどうするか

リアルタイム連携では、障害時の復旧まで考える必要があります。

Webhookだけに依存せず、定期的なAPI同期を併用するケースもあります。

Webhookの基本構成

例えば決済サービスからWebhookを受信する場合です。

外部サービス
↓
POST
↓
https://example.com/api/webhooks/payment
↓
自社サーバー
↓
イベント確認
↓
DB更新

という流れになります。

Webhook URLは外部サービスからアクセスできる必要があります。

Webhookで受信するデータ例

例えば、

event_id: evt_123
type: payment.completed
payment_id: pay_456
created_at: 2026-07-30T10:00:00Z

というイベントです。

自社システムでは、

payment.completed

を確認し、

支払い済み

へ変更します。

Webhookはイベント単位で処理する

例えばイベント種類として、

PAYMENT_COMPLETED
PAYMENT_FAILED
SUBSCRIPTION_UPDATED
SUBSCRIPTION_DELETED

などを定義します。

受信後、

event.type

によって処理を分けます。

重要なのは、Webhook URLをイベントごとに大量に分けることではなく、業務上どのイベントへ対応する必要があるかを整理することです。

Webhookで最も重要な「重複処理」

Webhookでは、

同じイベントが複数回来る可能性がある

ことを前提に設計します。

例えば、

決済成功
↓
Webhook受信
↓
ポイント100付与

という処理があるとします。

同じWebhookを2回受信すると、

200ポイント

付与されてしまう可能性があります。

そのため、

event_id

などを保存します。

例えば、

webhook_events

テーブルを作り、

event_id：evt_123
processed_at：2026-07-30 10:00

を記録します。

再びevt_123が来た場合は、

処理済み
→ スキップ

とします。

Webhook処理では冪等性を考える

何度実行しても結果が変わらない性質を冪等性と呼びます。

Webhook処理では重要な考え方です。

例えば、

status = paid

という更新なら、2回実行しても最終結果はpaidです。

一方、

points = points + 100

なら2回処理すると結果が変わります。

そのため、

Event IDを保存する
対象データの状態を確認する
一意制約を使う

などで二重処理を防ぎます。

Webhookは到着順を信用しすぎない

例えば、

SUBSCRIPTION_CREATED
↓
SUBSCRIPTION_UPDATED

という順番で発生したとしても、ネットワーク状況などによって処理順を前提にしない方が安全です。

例えば、

UPDATED
↓
CREATED

のような順序でも壊れないようにします。

その方法として、

Webhook受信
↓
対象ID取得
↓
APIで最新状態取得
↓
自社DB更新

という設計があります。

イベントの内容だけで状態を組み立てず、最新状態を取得する方法です。

Webhook受信後は早くレスポンスを返す

Webhook処理で、

受信
↓
大量データ処理
↓
メール送信
↓
AI処理
↓
DB集計
↓
200 OK

という構成にすると、処理時間が長くなる可能性があります。

外部サービスによっては、一定時間レスポンスがなければ送信失敗と判断し、再送することがあります。

そのため、

Webhook受信
↓
検証
↓
キューへ登録
↓
200 OK

その後、

非同期処理
↓
DB更新
↓
通知

という構成も検討します。

Webhookでは再送を前提にする

送信側から見ると、

Webhook送信
↓
自社サーバー障害
↓
受信失敗

というケースがあります。

Webhookを提供するサービスによっては再送機能があります。

そのため受信側でも、

同じイベントの再送
時間が経ってからの受信

を想定します。

Webhookが来なかった場合も考える

Webhookは便利ですが、

必ずリアルタイムで受信できる

という前提だけで業務を組むのは危険です。

例えば、

Webhook受信
↓
自社DB更新

だけに依存すると、何らかの理由でイベント処理に失敗した場合に、

外部サービス：契約済み
自社DB：未契約

というズレが発生する可能性があります。

そこで重要なシステムでは、

1日1回APIで契約情報を照合

などの同期処理を組み合わせる方法があります。

つまり、

Webhookでリアルタイム同期し、APIで定期的に整合性を確認する

という設計です。

APIポーリングとWebhookの使い分け

例えば注文情報を同期するとします。

APIポーリング

5分ごとに、

GET /orders?updated_after=…

を実行します。

メリット

実装が比較的単純
自分のタイミングで取得できる
障害復旧を制御しやすい

デメリット

更新がなくてもAPIを呼ぶ
最大5分の遅延
API利用制限に注意

Webhook

注文作成時に、

ORDER_CREATED

を受信します。

メリット

反映が速い
不要なAPIアクセスを減らせる

デメリット

Webhook受信URLが必要
重複処理が必要
再送・署名検証が必要
障害時の同期方法を考える必要がある

APIだけで十分なケース

例えば、

毎朝6時に売上データを同期

という業務なら、リアルタイム性は不要です。

この場合、

毎朝6時
↓
API
↓
前日売上取得
↓
DB保存

で十分です。

わざわざWebhookを実装する必要はありません。

Webhookが効果的なケース

例えば、

オンライン予約
↓
予約成立
↓
すぐスタッフへ通知

という業務です。

5分ごとのAPI取得では、予約発生から通知まで最大5分かかります。

即時対応が必要ならWebhookが有効です。

APIとWebhookの具体例｜Stripeなどの決済連携

決済では、APIとWebhookを組み合わせる構成が典型的です。

API

自社システム
↓
決済セッション作成

Webhook

決済サービス
↓
決済成功通知
↓
自社DB更新

さらに必要であれば、

Webhook
↓
対象契約ID確認
↓
API
↓
最新契約状態取得

とします。

決済結果をブラウザの成功画面だけで判断するのではなく、サーバー間連携を利用します。

APIとWebhookの具体例｜顧客管理システム

例えば外部CRMと自社システムを連携します。

API

自社画面から新しい顧客を登録
↓
CRM API
↓
顧客作成

Webhook

CRM側で顧客情報変更
↓
Webhook
↓
自社システム更新

という双方向連携です。

APIとWebhookの具体例｜予約システム

外部予約サービスと連携する場合です。

予約作成
↓
Webhook
↓
自社システムへ予約登録

一方、

予約詳細を表示
↓
API
↓
最新予約情報取得

という使い分けができます。

APIとWebhookの具体例｜在庫連携

ECサイトと在庫管理システムを連携するとします。

注文発生
↓
Webhook
↓
在庫システムへ通知
↓
在庫引当

一方、

毎晩
↓
API
↓
在庫数照合

とすれば、リアルタイム連携と整合性確認を組み合わせられます。

Webhookのセキュリティで重要な署名検証

Webhook URLは外部からHTTPリクエストを受け取ります。

そのため、

Webhook URLへPOSTされたから正しいイベント

と判断してはいけません。

攻撃者が同じURLへ、

「決済成功」

という偽データを送信する可能性があります。

そのためWebhook提供サービスが署名機能を提供している場合は、

署名
シークレット
タイムスタンプ

などを検証します。

基本的な流れは、

Webhook受信
↓
署名検証
↓
正しい送信元と判断
↓
イベント処理

です。

Webhook URLを知っているだけで処理できる設計にしない

例えば、

POST /webhooks/payment

へ、

status: paid
user_id: 123

を送れば有料会員になる

という設計では危険です。

Webhook送信元の正当性を確認します。

APIキーも適切に管理する

APIでは、

APIキー
アクセストークン
OAuth

などを利用します。

秘密情報をブラウザへ直接埋め込まず、サーバー側で管理します。

例えば、

ブラウザ
↓
自社バックエンド
↓
外部API

という構成です。

Webhookのログを残す

Webhook連携では、

「データが同期されていない」

という問題が起こったときに調査できることが重要です。

例えば、

event_id
event_type
受信日時
処理結果
エラー内容

を保存します。

例えば、

event_id: evt_123
event_type: subscription.updated
received_at: 2026-07-30 10:00
status: SUCCESS

という情報です。

Webhookの生データを永久保存する必要はない

デバッグのためにWebhookのpayloadを保存する方法もあります。

ただし、

個人情報
決済情報
機密情報

が含まれる可能性があります。

必要な情報だけ保存することや、保存期間を決めることも重要です。

Webhookエラーを確認できる管理画面も有効

重要な連携では、

Webhook処理一覧

日時
イベント
対象
結果
再処理

という管理画面を用意する場合があります。

例えば、

FAILED

となっているイベントを管理者が確認できます。

障害のたびにサーバーログを調べる必要を減らせます。

手動再処理機能をどう考える？

Webhook処理に失敗した場合、

「再実行」

できる管理機能を用意する場合があります。

ただし再実行によって、

二重登録
二重決済処理
二重通知

が起きないようにします。

ここでも冪等性が重要です。

API連携ではレート制限も考える

外部APIには、

1分100回まで

などの利用制限が設定されている場合があります。

大量のポーリングを行うと、制限に達する可能性があります。

例えば利用者1,000人が、それぞれ画面から外部APIを直接呼ぶ設計より、

自社システムで必要な情報を同期

した方がよい場合もあります。

Webhookは不要なポーリングを減らす手段にもなります。

API連携ではタイムアウトも考える

例えば、

ユーザーが保存ボタン
↓
外部API
↓
応答待ち

という場合、外部APIが遅いと自社システムも遅くなります。

そのため、

タイムアウト
リトライ
非同期処理
エラー表示

を設計します。

外部システムは常に正常とは限らない前提が必要です。

WebhookとWebSocketは別物

名前が似ているため混同されることがあります。

Webhook

サーバーから別のサーバーへイベント通知。

WebSocket

ブラウザなどとサーバーの接続を維持して双方向通信。

例えば、

決済サービス
↓ Webhook
自社サーバー
↓ WebSocket
ユーザー画面

という組み合わせも可能です。

つまり、

決済成功
↓
Webhook受信
↓
DB更新
↓
WebSocket
↓
画面へ「決済完了」をリアルタイム表示

という構成です。

WebhookとAPIを設計する7ステップ

STEP1｜連携する業務を整理する

例えば、

決済
顧客
予約
在庫
メール

などです。

STEP2｜どちらのシステムで変化が発生するか確認する

自社システムの操作
→ API

外部システムの変化
→ Webhook候補

と考えます。

STEP3｜必要なリアルタイム性を決める

例えば、

即時
1分以内
1時間以内
1日1回

などです。

即時でなくてもよければバッチAPI連携でも十分です。

STEP4｜Webhook対象イベントを決める

すべてのイベントを受信する必要はありません。

業務で必要なイベントだけ選びます。

STEP5｜APIで取得する情報を決める

Webhook通知だけで十分なのか、通知後にAPIから詳細取得するのか決めます。

STEP6｜障害時処理を決める

例えば、

再送
再試行
定期同期
手動再処理

などです。

STEP7｜セキュリティを設計する

例えば、

API認証
Webhook署名検証
秘密情報管理
通信ログ

などです。

【コピペ用】API・Webhook連携設計シート

連携概要

連携元：

連携先：

対象業務：

API

取得：

登録：

更新：

削除：

Webhook

イベント名：

通知タイミング：

対象ID：

リアルタイム性

即時：

1分以内：

1時間以内：

バッチ：

Webhook処理

Event ID：

重複防止：

署名検証：

処理結果保存：

エラー

再送：

再試行：

手動再処理：

定期同期

API照合：

実行頻度：

差分修正：

セキュリティ

APIキー：

アクセストークン：

Webhook Secret：

ログ：

運用

監視：

エラー通知：

管理画面：

Webhook連携でよくある失敗

失敗1｜リアルタイムだから何でもWebhookにする

1日1回の同期で十分ならAPIバッチの方が簡単です。

業務上必要な更新速度から判断します。

失敗2｜Webhookの重複を考えない

同じイベントを複数回処理する可能性を考えます。

Event IDなどで重複を防ぎます。

失敗3｜イベント順序に依存する

受信したイベントだけで状態を組み立てず、必要に応じてAPIから最新状態を取得します。

失敗4｜署名を検証しない

外部から偽イベントを送信されないようにします。

失敗5｜Webhook内で重い処理をする

受信後は必要に応じて非同期処理へ切り離します。

失敗6｜Webhookだけを信用して定期照合しない

重要なデータはAPIによる整合性確認も検討します。

失敗7｜失敗ログを残さない

同期されなかった原因を後から確認できません。

失敗8｜APIを呼びすぎる

ポーリング頻度やAPIレート制限を確認します。

失敗9｜外部API障害を考えない

タイムアウト・再試行・エラー時の業務継続方法を決めます。

失敗10｜WebhookとWebSocketを混同する

Webhookは主にシステム間のイベント連携、WebSocketはリアルタイムな双方向通信に利用します。

APIとWebhookに関するよくある質問

APIとWebhookの一番大きな違いは何ですか？

通信を開始する側です。

APIは自社システムから外部サービスへリクエストします。

Webhookは外部サービス側でイベントが発生したとき、自社システムへ通知してもらいます。

Webhookだけでシステム連携できますか？

ケースによります。

Webhookはイベント通知に向いていますが、詳細データ取得や登録・更新にはAPIを組み合わせることがあります。

WebhookがあればAPIのポーリングは不要ですか？

通常はポーリングを減らせます。

ただし重要なデータでは、Webhook取りこぼしなどに備えて定期的なAPI同期を併用する場合があります。

Webhookはリアルタイムですか？

一般的にはイベント発生後すぐ通知される仕組みとして使われます。

ただしネットワークや送信側の処理などもあるため、「必ず瞬時に届く」前提では設計しない方が安全です。

Webhookを受信したら、そのデータをそのまま信用してよいですか？

送信元の検証が必要です。

提供元が署名検証の仕組みを用意している場合は利用します。

同じWebhookが2回来ることはありますか？

あり得る前提で実装することをおすすめします。

Event IDなどを利用して重複処理を防ぎます。

WebhookとWebSocketはどちらを使えばよいですか？

用途が異なります。

外部サービスから自社サーバーへイベントを通知してほしい場合はWebhook。

ブラウザとサーバー間でリアルタイム通信したい場合はWebSocketが候補です。

hiro-dev-labではAPI・Webhook連携の設計から相談できます

hiro-dev-labでは、単純に外部APIを接続するだけでなく、どの処理をAPI・Webhookのどちらで連携するべきか整理する段階から相談できます。

例えば、

外部サービスとのAPI連携
Webhook受信
リアルタイムデータ同期
定期バッチ同期
APIポーリング
Webhook署名検証
重複イベント対策
再送・再試行
外部サービス障害時の設計
連携ログ
管理画面
決済サービス連携
顧客・予約・在庫連携
要求整理
業務要件・機能要件整理
Webシステム設計・開発

などです。

例えば、

APIを定期実行しているがリアルタイム化したい

StripeなどのWebhookをどう自社DBへ反映すればよいか分からない

外部サービスとのデータ同期でズレが発生している

Webhookだけに任せてよいのか判断したい

という場合でも、

業務イベント → 必要な更新速度 → API・Webhook → 障害時同期 → 運用

の順番で整理できます。

まとめ｜APIとWebhookは競合する技術ではなく役割を分けて使う

APIとWebhookを比較すると、

「どちらを使えばよいのか」

という二者択一で考えがちです。

しかし、実際のシステム連携では両方を組み合わせるケースが多くあります。

基本的には、

API

こちらから、

「情報を取得したい」

「データを登録したい」

「処理を実行したい」

という場合に利用します。

Webhook

外部サービス側で、

「決済された」

「契約が変更された」

「予約された」

などのイベントが発生したことを知らせてもらう場合に利用します。

さらに、

Webhook
↓
イベント発生を検知
↓
API
↓
最新データ取得
↓
自社DB更新

という組み合わせも有効です。

連携を設計するときは、

どちらのシステムでイベントが発生するか
何秒以内に同期する必要があるか
詳細データを取得する必要があるか
重複イベントをどう防ぐか
Webhook失敗時にどう復旧するか
定期API同期が必要か
送信元をどう検証するか

を整理します。

特に重要なのは、

Webhookを「絶対に1回だけ届く通知」と考えないこと

です。

重複・遅延・取りこぼし・順不同などを考慮し、

冪等な処理
署名検証
処理ログ
再試行
必要に応じたAPI再取得

を設計します。

APIとWebhookを適切に使い分けることで、

リアルタイム性とデータ整合性の両方を考慮した外部システム連携

を構築しやすくなります。