加密貨幣結帳會發出哪些事件?

InfraIO Pay 每次狀態轉換都會觸發一個 webhook。這個狀態機刻意設計得很精簡，讓你能將履約邏輯精確綁定到單一事件，忽略其餘事件。

  • payment.pending，買家已廣播交易；確認數仍在累積中。
  • payment.confirmed，交易已達到該網路的確認閾值。
  • payment.settled，款項已歸集至你的結算錢包。請在此履約。
  • session.expired，結帳視窗未付款即關閉。永遠不會被收費。

應該在哪個事件上履約?

請在 payment.settled 上履約。處於 pending 狀態的交易仍可能確認失敗，而確認閾值因網路而異，因此若把更早的狀態當作最終結果，就有對一筆永遠不會入帳的付款出貨的風險。結算(settlement)正是這筆款項不可逆地歸你所有的那一刻。

如果你需要向買家顯示進度，可以在 UI 中呈現 pending 與 confirmed 狀態，但務必將不可逆的動作(出貨、授予存取權、鑄造)綁定到 settled。

如何驗證 webhook 是真實的?

每個 webhook 都會以你的端點密鑰簽章。對原始請求主體重新計算 HMAC，並以固定時間(constant-time)與簽章標頭比對；任何不相符的請求都應拒絕。若你剛接觸 HMAC，MDN 的 SubtleCrypto.sign 參考文件是很好的入門資料，Stripe 的 webhook 最佳實務指南則對維運層面有完整說明。

先驗證，再解析或處理。未簽章或簽章錯誤的請求絕不應觸及你的業務邏輯。

如何讓投遞能安全地重試?

Webhook 採用至少一次(at-least-once)投遞，因此在一次網路短暫故障之後，同一個事件可能不止一次送達。每個事件都帶有一個 idempotency key；請記錄你已處理過的金鑰，對重複事件不做任何處理(no-op)。快速回應 2xx，並將耗時的工作以非同步方式處理，避免發送端逾時並進行不必要的重試。InfraIO 保留一份投遞紀錄，並支援一鍵 replay，供你需要刻意重新處理時使用。