Webhookとポーリング：適切な統合アプローチの選び方

データ同期で解くべき問題は何か？

同期と言うと「更新を速く反映する」ように聞こえますが、本当の仕事はもっと厳しい：メッセージが遅れたり重複したり欠落していても、二つのシステムが何が正しいか合意することです。

Webhookとポーリングの違いは、変更をどう知るかにあります。

Webhookはプッシュです。システムAでイベントが発生したら（例：「payment_succeeded」や「invoice paid」）Aがあなたのエンドポイントを呼び出します。ポーリングはプルです。あなたのシステムが定期的に「前回以降何かある？」とシステムAに問い合わせます。

システムを同期させるには通常、イベントと状態の両方を追跡します。イベントは何が起きたかを伝え、状態は現在のレコードの姿を示します。時系列は重要です。統合は完璧な順序で動くことは稀で、"updated" イベントが "created" より先に届くことも、二重に届くことも、まったく届かないこともあります。

目標は「新しさ」だけでなく「正しさ」です。正しいとは、変更を見逃さず、同じ変更を二度適用せず、ダウンタイムから手作業なしで復旧でき、いつ何を処理したか証明できることを意味します。

実例：支払いプロバイダが "payment_succeeded" のWebhookを送ってあなたのアプリが注文を作成して有料にする。Webhookエンドポイントが短時間ダウンしていると、そのイベントを見逃すかもしれません。"昨日以降に更新された支払い" を問い合わせるポーリングジョブが、そのギャップを埋めて注文状態を修正できます。

多くの実用的な統合は両方を使います：速度のためにWebhook、バックフィルや検証のためにポーリング。重要なのはどちらを選ぶかではなく、周囲の安全策です。

レイテンシと鮮度：実際に更新が届く速さ

Webhookとポーリングを比べるとき、多くの人が意味するのは「相手の変更にどれだけ早く気づくか」です。この鮮度は単なる贅沢ではなく、サポートチケット、重複作業、ユーザの信頼に影響します。

ポーリングはスケジュールに従うため遅延が内在します。5分ごとにポーリングするなら、数秒から最大ほぼ5分の遅れに加えAPI応答時間がかかります。ポーリング頻度を上げれば鮮度は良くなりますが、APIコール、コスト、レート制限に当たる可能性が増します。

Webhookはプロバイダが何か起きたら即座にプッシュするのでリアルタイムに近く感じられますが、決して瞬時でも保証されてもいません。プロバイダはイベントをバッチしたり、後でリトライしたり、配信を停止することがあります。あなたのシステム側でも（キューの滞留、データベースロック、デプロイ）遅延が発生します。より現実的な期待値は：調子が良ければ速いが、そうでないときは最終的に整合する、ということです。

トラフィックの形状も重要です。ポーリングは安定した予測可能な負荷を与えます。Webhookはバースト的です：繁忙時間に1分で数百のイベントが来て、その後しばらく何も来ないことがあります。Webhookを受け入れるならスパイクを想定し、イベントをキューに入れて制御された速度で処理できるように計画してください。

設計前に目標となる鮮度ウィンドウを決めましょう：

• 秒単位：ユーザ向け通知、チャット、支払いステータス
• 分単位：サポートツール、管理画面、軽量なレポート
• 時間単位：夜間リコンシリエーション、優先度の低い分析

営業チームが1分以内に新規リードを見たいならWebhookが適しています。数時間ごとの“安全なポール”で見逃したイベントをキャッチし最終状態を確認するのが有効です。

本番で実際に見る障害モード

多くの統合は退屈で再現可能な方法で壊れます。驚きは何かが壊れることではなく、静かに壊れることです。速度の議論は容易ですが、信頼性が本当の仕事です。

ポーリングの失敗は「更新を見ていなかった」に見えることが多いです。タイムアウトでリクエストが途中で切れる、HTTP 200 だけを見てレスポンスボディを検証しないために不完全なレスポンスが通る、ページネーションの変更（ソート順の変更、ページ番号からカーソルへの移行）で項目をスキップしたり重複読みに陥る、ローカルの時計を基準に "updated_since" をフィルタしてプロバイダと時計がずれたため更新を見逃す、などがよくある問題です。

Webhookの失敗は異なります。配信は通常 "at least once" なので、プロバイダはネットワークエラー時にリトライし、結果として重複を目にします。エンドポイントが10分間ダウンしていると古いイベントが一度にやってくることがあります。署名検証の問題も頻出：シークレットがローテーションされた、誤った生ペイロードを検証した、プロキシがヘッダを改変した、などで正当なイベントが無効と判定されることがあります。

両方に共通する障害モードは重複と順序の乱れです。同じイベントが複数回届く、遅れて届く、順序が入れ替わる、想定していないフィールドが欠けていることを想定してください。

ほとんどの場合「ちょうど一度」は得られません。"最低一度" を前提に設計し、安全に処理できるようにします。idempotencyキー（イベントIDやプロバイダのオブジェクトバージョン）を保存して重複を無視し、保存済みのものより新しい場合にのみ更新を適用します。また何を受け取って何をしたかをログに残し、推測でなく自信を持ってリプレイできるようにします。

レート制限とコスト：API使用を抑える

レート制限はWebhook対ポーリングの議論が理論から予算と信頼性の問題になる領域です。余分なリクエストは時間と金を消費し、プロバイダとの関係を損ねる可能性があります。

ポーリングは何も変化がなくてもチェックするためクォータを消費します。ユーザやトークン単位で制限があると悪化します：例えば1000人の顧客が毎分ポーリングすると、それぞれは「適切に振る舞っている」かもしれませんが、合算すると攻撃のように見えます。ポーリングはまたコールの掛け算を生みやすく（リスト取得の後に各アイテムを詳細取得）制限に達する原因になります。

Webhookは通常APIコールを減らしますが、バーストのプレッシャーを生みます。プロバイダが障害から回復したり一括インポートを行ったり製品ローンチがあると、何千というイベントを一度に配信するかもしれません。プロバイダは429でサージを制限したり、あなたが遅いとイベントをドロップしたりします。受け側はバックプレッシャーを設計する必要があります：すばやく受け入れてキューに入れ、制御されたペースで処理する。

呼び出しを減らしつつ正確性を損なわないための実践的パターン：

• “updated since” タイムスタンプや変更トークンを使った増分同期
• サーバサイドのフィルタ（必要なイベントタイプだけ購読）
• 読み取り・書き込みのバッチ化（詳細はチャンクで取得、書き込みはまとめて）
• 安定した参照データのキャッシュ（プラン、ステータス一覧、プロフィール）
• “リアルタイム” と “レポーティング” を分離（高速経路と夜間バッチ）

ピークに備えて計画を立てておきましょう。専用のバックフィルモードを用意し、遅く動かしクォータを尊重し一時停止・再開できるようにします。

正しいアプローチの選び方：簡単なガイド

Webhookかポーリングかの選択はたいていこういう問いに落ち着きます：速度が必要か、それともベンダが信頼できないときでも確実に更新を得られる予測可能さが必要か？

第三者がWebhookを提供していない、またはワークフローが遅延を許容するならポーリングが初期の良いデフォルトです。日次や時次の同期でAPIに "updated since" フィルタがあるなら考えやすくなります。

時間が重要ならWebhookがデフォルトで優れています：「新しい注文が入った」「支払いに失敗した」「チケットが割り当てられた」など。無駄なAPIコールを減らし即座に処理をトリガーできます。

正確さが重要なら両方を使うのが実用的なルールです。Webhookで速度を取り、ポーリングで見逃しを補う。例えばWebhookは素早く処理し、15分ごと（または数時間ごと）にスケジュールされたポーリングを走らせてドロップされたイベントや一時的な停止で生じたギャップを埋めます。

簡単な指針：

• 数分の遅延で問題なければポーリングから始める。
• 数秒で表示する必要があればWebhookから始める。
• ベンダの信頼性が低いかイベントが重要ならWebhook＋ポーリングを計画する。
• APIが厳しいレート制限ならWebhook＋軽めのポーリングを優先する。
• データ量が多いなら頻繁なフルポールは避ける。

確定前にベンダにいくつか質問して明確な回答を得てください：

• どのイベントタイプがあり、作成・更新・削除が網羅されているか？
• Webhookはどのようにリトライするか、どれくらいの期間リトライするか？
• イベントの再生や、時間範囲でのイベント履歴取得は可能か？
• Webhookリクエストに署名が付くか、真正性を検証できるか？
• 効率的なポーリングのために “updated since” クエリをサポートしているか？

ステップバイステップ：正しさを保つ同期設計

「正しい」同期は単にデータが出現することではありません。正しい同期とは適切なレコードが一致し、最新の変更が勝ち、問題が起きたときに何が起きたか証明できることです。

テストと監視ができる計画から始めましょう：

1. 定義：どちらが真実のソースかとルールを決める。フィールドごとに責任の所在を決める（例：CRMが顧客名を所有し、請求ツールがサブスクリプション状態を所有する）。「十分に新しい」とは何分以内か、許容できるエラーは何かを決める。
2. 安定した識別子を選ぶ。サードパーティの固有IDを内部IDと並べて保存する。メールや名前をキーにしない（変更されるため）。可能ならバージョンや "updated_at" タイムスタンプを保存して新しいデータか検出する。
3. 初期インポートと増分更新を計画する。初回インポートはチェックポイント付きの別ジョブとして扱い、再開可能にする。その後は変更のみを処理（イベント、"since" クエリ、またはその両方）し "last successful sync time" のようなカーソルを記録する。
4. 削除とマージを意図的に扱う。削除でレコードを消すかアーカイブするか非アクティブにするか決める。マージはどのIDを残すかを決め、監査証跡を保持する。
5. 監視シグナルを設定する。同期遅延、失敗した呼び出し、詰まったキューを追跡し、閾値を超えたらアラートする（単にクラッシュしたときだけでなく）。

実装するときは外部ID、タイムスタンプ、ステータスフィールド、同期チェックポイントをデータモデルで見えるようにしておきます。現実世界が乱れてもこれらの構造が同期を正しく保ちます。

冪等性と順序：信頼できる統合の核心

Webhookとポーリングを長く作っていると毎回見えてくるルールがあります：重複、リトライ、順序の乱れは必ず起きます。同期が同じメッセージを安全に再処理できないなら、時間とともに差分が生じます。

冪等性とは「同じ入力なら同じ結果」を意味します。すべての着信イベントを「繰り返されるかもしれない」と扱い、ハンドラを安全に設計します。一般的なパターンは：重複除去キーを算出し、既に処理済みか確認してから変更を適用する、です。

重複除去キーにはトレードオフがあります。プロバイダがイベントIDを与えるならそれが最良です。なければオブジェクトのバージョン（増分リビジョン）を使うか、"10分間は重複を無視する" のようなタイムスタンプウィンドウは遅延到着があるため脆弱です。

順序はもう一方の半分です。グローバルな順序は稀なので、オブジェクト単位の順序を目標にします。チケットや請求書、顧客の更新は保存済みより新しいバージョンなら適用します。バージョンがなければ last-write-wins（例えば newer updated_at が勝つ）を明確なルールで採用し、時計ずれのエッジケースは受け入れる設計にします。

再生や復旧のために十分な情報を保持します：

• 各オブジェクトの "last seen" バージョンや updated_at
• ポーリングジョブの最後に処理したカーソルやチェックポイント
• 処理済みイベントIDのテーブル（急速に増える場合は保持方針を設ける）
• 一時的に保持する raw payload で、修正を再実行できるようにする

例：Stripeの支払いWebhookが二度届き、その後 "paid" 更新が "created" イベントより先に来た場合でも、請求書の最新ステータスバージョンを保存し古い更新を無視すれば正しい状態になります。

サイレントなデータずれを防ぐ再試行と再生パターン

多くの統合は静かに失敗します。Webhookが遅れて届く、ポーリングが制限に当たる、アプリが保存中にタイムアウトする。再試行と再生がなければシステムは徐々にずれていき、顧客からの苦情で初めて気づきます。

Webhookの再試行：速く受け入れ、安全に処理する

プロバイダは成功コードが速やかに返らないとリトライすることが多いです。Webhookリクエストを重い処理の場と考えず、配信通知として扱ってください。

実践的なWebhookパターン：

• 署名、スキーマ、タイムスタンプの基本検証後に速やかに2xxを返す。
• イベントを一意ID付きで保存し保留中にマークする。
• ワーカーで非同期に処理し試行回数を追跡する。
• 一時的エラーなら後で再試行し、恒久的エラーなら停止してアラートする。
• 不正なデータには4xx、サーバトラブルには5xxを使う。

これでよくある罠を避けられます：「Webhookを受け取った＝データが同期した」と思い込むことです。

ポーリングの再試行：APIに礼儀正しく

ポーリングの失敗は別物です。短い停止後にリトライの群れが発生しレート制限を悪化させるリスクがあります。指数バックオフ＋ジッターを使い、"since" カーソルを保持して全件再スキャンを避けてください。

今処理できないものはデッドレターキュー（またはテーブル）に入れて理由を記録しましょう。これにより安全に検査、マッピング修正、再実行ができます。

再生は見逃したイベントを回復する方法です。簡単な再生戦略：

• 時間窓を選ぶ（例：過去24時間）か、対象レコード群を選ぶ。
• プロバイダから現在の状態を再取得する。
• 冪等に更新を再適用して不整合を修正する。
• 何が変わり、なぜかを記録する。

例：請求のWebhookで "invoice.paid" を受け取ったがデータベースがロックされ30秒保存できなかった場合、イベントをデッドレターに入れ、請求書と支払いステータスを再フェッチしてレコードを合わせることで再生できます。

よくあるミスと回避法

多くの同期バグは大きなアーキテクチャ問題ではなく、小さな前提のすれ違いです。それが静かなずれ、重複レコード、見逃しにつながります。

繰り返し出る失敗例：

• 増分フィルタなしに頻繁にポーリングする。 カーソル（updated_at、イベントID、ページトークン）を追跡し、最後の成功実行以降の変更だけを問い合わせる。
• Webhookを保証された配信とみなす。 最近の履歴（過去24〜72時間など）を再チェックするバックフィルジョブを持つ。
• 重複を無視する。 すべての書き込みを冪等にする。プロバイダのイベントIDや安定した外部IDを保存し、同一変更を二度適用しない。
• 検証なしにWebhookを受け入れる。 プロバイダが提供する署名トークンや検証手段を使って検証する。
• 同期の健康状態を見ていない。 遅延、バックログのサイズ、最後の成功実行時刻、エラー率を追跡し、閾値を超えたらアラートする。

多くの "Webhook vs Polling" の議論は要点を外しています：信頼性はどちらかの手法そのものではなく、その周囲にある安全策から生まれます。支払いWebhookが二度届くか遅れて届く可能性を考慮せず、Webhookで直接レコードを作成すると顧客に二重でメッセージを送ったり請求したりする恐れがあります。

健全な統合のためのクイックチェックリスト

日常の健康チェックはWebhook、ポーリング、または双方で似ています。データが新しいか、エラーが積み上がっていないか、クリーンに復旧できるかを知りたいはずです。

数分で実行できるチェックリスト：

• 鮮度： 「最後にイベントを受け取った時間」や「最後のポール完了時間」を期待遅延と比較する。
• 失敗： リトライが増え続けていないか、動いていないジョブがないか。エラー数と「最後の成功」時刻を組み合わせて見る。
• クォータ： 使用したAPIコール数と残りを確認。限界に近いならポーリングを遅らせバッチ化する。
• 正確性： システム間で合計（例えば「今日の注文数」）をスポットチェックし、最近のレコードをいくつかサンプリングする。
• 復旧準備： 重複や見逃しなく最近の時間窓を安全に再処理できることを確認する。

役立つ習慣は、既知の繁忙期を制御下で定期的に再生し、結果が本番と一致することを確認することです。

例：現実的なワークフローでWebhookとポーリングを混ぜる

小さなSaaSチームがCRM（連絡先と案件）、Stripe決済（課金と返金）、サポートツール（チケット状態）の三つを同期させる必要があるとします。

高速反応が必要なものはWebhook優先で設定します。CRMイベントは顧客レコードを更新し内部タスクをトリガーします。StripeのWebhookは請求書を作成し、支払い後に機能を解放し、失敗時にアカウントを未払いにします。サポートツールはWebhookがあれば使いますが、チケットが一括で状態変更されることがあるため定期ポーリングも維持します。

彼らはポーリングをメインではなくセーフティネットとして扱います。毎晩、過去24時間の変更を各システムから取得してアプリが保持しているものと照合するリコンシリエーションジョブを走らせます。

あるとき現実の障害が起き、デプロイ中にWebhookエンドポイントが20分間ダウンしました。

• CRMとStripeはしばらくのあいだリトライします。
• 一部のイベントは遅れて届き、順序が入れ替わり、期限切れになるものもあります。
• リコンシリエーションポールがギャップ（欠損したイベントIDや不一致の合計）を検出し欠けている変更をバックフィルします。

彼らがログに残すもの：受信イベントID、プロバイダのタイムスタンプ、内部レコードID、最終結果（作成・更新・無視）。アラートのトリガーは繰り返すWebhook失敗、リトライの急増、またはリコンシリエーションが小さな閾値以上の欠損を見つけたときです。

次のステップ：実装、監視、反復

多くのチームにとって実用的なデフォルトはシンプルです：即時性はWebhook、補完は小さなポーリングジョブで。Webhookで素早く届くようにし、ポーリングで障害や設定ミスで見逃したものを補う。

まずは速さよりも正確さを優先してください。すべての着信変更を何度処理されても安全に適用できるようにします。

最初に取るべき3つのアクション：

• ベンダのイベントとフィールドを内部モデルにマップする。"delete"、"refund"、"status change" があなたのシステムで何を意味するかを明確にする。
• 初日から冪等性を設計する：外部イベントIDやバージョンを保存し、再生しても重複が起きないようにする。
• 意図的に再生を追加する："last seen" カーソルや時間窓ポーリングを保持し、問題があった範囲を管理者が再実行できるようにする。

稼働後は監視が運用を支えます。Webhook配信率、理由別の失敗（タイムアウト、4xx、5xx）、リコンシリエーションポールの遅れを追跡しましょう。"イベントがまったく受信されていない" ことにもアラートを上げる習慣をつけてください。

手作業でフルバックエンドを書くのではなく視覚的ツールでこれを作りたい場合、AppMaster (appmaster.io) はデータモデルの設計、Webhookエンドポイント作成、再試行/再生フロー設計をビジュアルに行えるノーコードオプションで、必要に応じて実際のソースコードも生成します。