メール配信 Webhook イベントとプリペイドウォレット残高の照合

イベント駆動型メール課金の仕組み

メール送信などのトランザクション通信を SMS や OTP などの優先度の高いチャネルとともに処理する場合、財務口座の同期を正確に維持することが非常に重要です。堅牢なプリペイド CPaaS 環境は、即時の残高検証に依存しています。送信が開始されるたびに、配信試行がキューを離れる前に、アカウント残高に対して一時的な資金保留(Hold)が実行されます。IOSOR は USD 20 の必須プリペイドフロアで動作し、システムテナントがキューに入れられたメッセージに対して十分な流動性を維持できるようにします。リアルタイムの保留アーキテクチャがない場合、スパイク通信によって台帳が更新される前に残高が枯渇し、マイナス残高や勘定の不一致が発生する可能性があります。

複数チャネルのトラフィックを処理する際、課金エンジンの処理スピードは即時でなければなりません。事前保留処理により取引に一意の識別子が割り当てられ、インフラが配信処理を行っている間、正確な金額が凍結されます。これにより、高負荷時においても並行リクエストが未保有のクレジットを消費するのを防ぎます。

非同期配信 Webhook と台帳ステータス

メールの送信は本質的に非同期です。インフラストラクチャがペイロードを送信した際の即時レスポンスは受領を確認するものであり、最終的な受信箱への配信完了を保証するものではありません。メッセージが配信ステージを進むにつれて、Webhook は配信完了(delivered)、バウンス(bounced)、ドロップ(dropped)、保留(deferred)などの詳細なイベントを報告します。

メールが受信側のメール転送エージェント(MTA)に正常に引き渡されると、最初の保留は台帳上の永久的な引き落とし(Debit)に移行します。逆に、ハードバウンスが発生した場合、保留は即座に解除または返金され、未配信のメッセージによる残高の減少を防ぎます。この状態遷移は、テナントの実際の資金状態を正確に反映するために厳格に不可分(アトミック)でなければなりません。

バウンスおよびドロップイベントでの二重課金の防止

二重課金を防止するには、メッセージ識別子と財務取引記録の間に厳密なライフサイクルマッピングが必要です。E.164 宛先 SMS、DLR ステータス更新、メール通知を含む混合トラフィックを扱う大規模な環境では、リトライメカニズムによって重複した Webhook ペイロードが発生する可能性があります。

単一のメール再試行に対してテナントに二重課金するのを防ぐため、課金エンジンは受信した Webhook イベント ID を最初の承認保留と関連付ける必要があります。ドロップイベントが保留ステータスの後に続く場合、システムは一時的な保留が調整済みかどうかを評価します。イベントの重複排除により、複数の通知が送信された場合でも顧客の最終残高が誤って変更されるのを防ぎます。

配信キュー間における冪等性キーの照合

冪等性キー(Idempotency Keys)は、非同期処理パイプライン全体で財務操作の原子性を維持することを保証します。アプリケーションが一意の冪等性トークンを使用してメールリクエストを送信すると、課金システムは取引保留とともにペイロードの意図を記録します。ネットワークタイムアウトによってクライアントの再試行が発生した場合、バックエンドはトークンを照合し、重複した台帳エントリを防止します。

テナントのメッセージスループットが拡大し、アカウント消費が月額 USD 1,000 付近のソフトレビューしきい値に近づくと、厳格な冪等性の適用により、軽微なリトライループによる財務上の不整合や不必要なアカウント制限を防ぐことができます。

ウォレット照合のための運用上のベストプラクティス

配信メトリクスとテナント残高を完全に一致させるために、未完了の保留を定期的に監査するイベント駆動型の照合ルーチンを実装してください。監査ログにすべての Webhook コールバックと対応する台帳 UUID を記録していることを確認します。

実装の技術的詳細については、同じプリペイド台帳上のメールに関するガイドを参照し、同一ウォレットのトランザクションメールアーキテクチャを確認し、をご相談ください。

関連ガイド: 同じプリペイド台帳上のメール · 同一ウォレットのトランザクションメール · 冪等・再試行と資金.

IOSOR で始める

inbound webhook を accepted / bounced / deferred / complained に購読する。各イベントを ledger の prepaid デビット行と同じ message-id に鍵付けする。webhook 再試行は冪等で、二度目の debit を出さない。確定 bounce のあとだけ返金し、遅い accepted や deferral では資金を戻さない。

IOSORの要点

Webhook は ledger のイベント真実である。Accepted は受信箱ではない。Complained は bounce 返金ではない。

する：資金を動かす前にイベントを debit に突き合わせる。しない：webhook 再試行を新規送信と見なすこと、deferral を bounce として入金すること。