整合
Webhook
接收 StableOps Agent Payments 的付款、資源回應、人工審批、鏈上結算與熔斷狀態 Webhook。正確驗證簽名、處理時間戳和重放保護、按事件標識去重、應對亂序投遞與重試，並使用原付款 Intent 完成可靠對帳。
Agent Payments 的狀態變化會與業務事務一起寫入事務發件箱，再透過 StableOps 的簽名 Webhook 管道投遞。投遞支援自動重試、端點併發限制、人工重放和死信處理。
設定端點
前往 Agent Payments Webhook 管理建立端點、輪換籤名金鑰、檢視投遞記錄，以及重放失敗或進入死信的投遞。
在這裡建立的端點會接收 agent_payment.* 事件。沙盒與正式環境需要分別設定。
兩條狀態軸
一筆 Agent 支付同時維護兩類狀態：
payment_status：策略、審批、授權和鏈上結算狀態。resource_status：付費 HTTP 請求是否收到可靠回應。
資源請求成功不等於鏈上已經結算。鏈上結算成功也不保證 Agent 收到了資源回應。履約、重試和人工對帳必須同時檢視
payment_status 與 resource_status。事件型別
| 類別 | 事件 |
|---|---|
| Intent | agent_payment.intent.created、agent_payment.intent.awaiting_approval |
| 審批 | agent_payment.approval.approved、agent_payment.approval.rejected、agent_payment.approval.expired |
| 授權 | agent_payment.authorization.issued、agent_payment.authorization.expired |
| 結算 | agent_payment.settlement.unknown、agent_payment.settlement.settled、agent_payment.settlement.reverted |
| 資源 | agent_payment.resource.succeeded、agent_payment.resource.failed、agent_payment.resource.unknown |
| 熔斷 | agent_payment.agent.paused、agent_payment.organization.paused |
settlement.unknown 表示付款請求可能已經送達結算服務，但目前證據不足以確認結果。此時只能查詢和對帳原 Intent，不能建立新 Intent 或新授權重付。
載荷結構
普通支付事件使用版本化信封：
{
"id": "7b91729e-41d0-4f9f-8dd1-6eea06a5764d",
"type": "agent_payment.settlement.settled",
"version": "1",
"occurred_at": "2026-08-05T08:00:00.000Z",
"data": {
"organization_id": "org_...",
"environment": "sandbox",
"agent_id": "agent_...",
"intent_id": "pint_...",
"payment_status": "settled",
"resource_status": "response_received",
"amount_atomic": "1000",
"asset": "USDC",
"asset_contract": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
"asset_decimals": 6,
"network": "eip155:84532",
"origin": "https://resource.example.com",
"pay_to": "0x...",
"approval_id": null,
"authorization_id": "pauth_...",
"receipt_id": "receipt_..."
}
}暫停事件只包含其適用的組織、環境、Agent 或暫停原因。任何載荷都不會包含 Agent Key、執行授權原文、完整支付簽名、私鑰或收費資源回應正文。
完整的版本化信封、全部事件名、欄位型別、必填與可空欄位，以及三類載荷變體，見 Agent Payments Webhook API 參考。
安全處理規則
- 使用原始請求體校驗 Webhook 簽名，驗籤成功後再解析 JSON。
- 以頂層
id建唯一索引去重。自動重試和人工重放都可能重複投遞同一事件。 - 先把事件持久化，再儘快返回
2xx。耗時業務處理放到自己的佇列中。 - 不假設跨事件嚴格有序。需要執行不可逆操作前，用
management.payments.get(intentId)查詢目前狀態。 - 收到
settlement.unknown、settlement.reverted或任一暫停事件時觸發告警和人工核對，不要自動重付。
端點建立、原始請求體驗籤、金鑰輪換、重試時序和死信重放見 Webhook 通用文件。
這篇文件怎麼樣？
最後更新