銀行エンジニアリング 31：イベントとWebhook（重複・順序・欠落・署名）

Level 1 基礎：通知は届かないことがある

インターネットを通る通知は、相手が落ちていれば届かず、再送すれば重なり、順番も保証されません。ここで通知を正本として資金を動かすと、二重に支払ったり、取りこぼしたりします。

そこで、銀行は起きた出来事を欠番のない『イベント列』として記録し、Webhookはその一部を知らせるだけにします。アプリはいつでもイベント列を取り直せます。

Level 2 銀行業務：アプリ側の決まり

通知が遅れても、重なっても、逆順でも、欠けても、金融の結果は変わりません。通知は結果を表示するだけで、資金を動かさないからです。

Level 3 システム：MiniBankでの実装

• openbanking.emit_event が、状態の変更と同じトランザクションでイベントを追記する。同意ごとに sequence は1から欠番なしで増える。追記専用で、更新も削除もできない（PF001）
• openbanking.run_deliveries は外部へ通信しない。購読ごとの『受信者の振る舞い』（正常／最初の1回だけ失敗／常に失敗／重複／逆順）に従って、配信の試行を記録する
• 失敗した配信は5回まで記録し、5回失敗したあとの次の実行で DEAD にする（初回を含めて5回の失敗）。DEAD になっても、イベントは events API から取れる
• 署名は X-MiniBank-Signature: t=<unix>,v1=HMAC-SHA256(鍵, t + "." + 本文)。鍵は購読の作成時に一度だけ返し、ログにも監査にも残さない
• openbanking.reconcile が、連番の欠落、依頼と振込の不一致、無効な同意で生きているトークンを検出する

異常時：DEADの通知が増えた

Level 4 アーキテクチャ：Outbox

状態の変更とイベントの記録を同じトランザクションにする設計を、Outboxと呼びます。片方だけが成功して『お金は動いたのに通知の元がない』状態を作らないためです。配信は別の仕事として、何度でもやり直せます。

どこを確認すればよいか

• 管理画面「Open Banking」のWebhookの購読・配信・イベント
• Lab：受信者の振る舞いを切り替えて、アプリ側の処理を確かめる