อย่าตกใจถ้าการแจ้งเตือนแลกเปลี่ยนเงินสูญหาย - สร้างระบบกระทบยอดแลกเปลี่ยนอัตโนมัติระดับสถาบันด้วย OnyxClearing Webhook
ทำไมการแจ้งเตือนการแลกเปลี่ยนสำเร็จจึงอาจสูญหาย: กระบวนการแลกเปลี่ยนของ OnyxClearing เป็นแบบอะซิงโครนัส ระบบของคุณส่งคำขอแลกเปลี่ยน USDT ระดับสถาบัน OnyxClearing ล็อกอัตราแลกเปลี่ยนหลังจากตรึงราคาในระดับมิลลิวินาที จากนั้นทำการ settle บนเชน บันทึกลงบัญชีแยกประเภท USD ที่ปฏิบัติตามกฎระเบียบ และสุดท้ายแจ้งเตือนบริการของคุณผ่าน webhook ทุกขั้นตอน — ไม่ว่าจะเป็นเครือข่ายขัดข้อง บริการรีสตาร์ท หรือ endpoint callback ตอบ 5xx — ล้วนอาจทำให้การแจ้งเตือนสูญหายหรือซ้ำกันได้
Published October 21, 2026 · ThisKard team
为什么换汇成功通知会丢
OnyxClearing(曜石承兑)的换汇流程是异步的:你的系统发起一笔机构级USDT换汇请求,OnyxClearing 在毫秒级定锚后锁定汇率,随后链上结算、合规USD账本入账,最后通过 webhook 通知你的服务。任何一环——网络抖动、服务重启、回调端点 5xx——都可能导致通知丢失或重复。
对 enterprise 客户而言,这不是小事。大宗稳定币结算动辄六七位数,一笔对不上账,财务月底就要手动翻链上浏览器和内部流水。正确的做法是:webhook 只当加速器,不当唯一事实来源,配一套定时对账兜底。
整体架构:三层防线
- Webhook 实时层:换汇完成立即收到事件,更新本地订单状态
- 签名验证层:防止伪造回调污染你的合规USD账本
- 主动对账层:定时调用
api.thiskard.com的查询端点,拉取最近结算记录,补齐漏单
对于走渐进式 KYB 通道的机构,建议对账任务按 KYB 层级区分频率:白名单层级客户可 5 分钟一轮,新通道客户 15 分钟一轮,这也是黑天鹅风险隔离策略的一部分——异常时可以单独降频或冻结某一客户群的对账管道,不影响其他轨道。
分步工作流
第 1 步:注册 webhook 端点
在 thiskard.com/developers 的控制台配置回调 URL,订阅 fx.settled、fx.failed、fx.flagged 三类事件。
第 2 步:接收并验证签名
每条回调头部带 X-Onyx-Signature(HMAC-SHA256)。务必验证,否则任何人都能向你推送假事件。
第 3 步:幂等处理
事件可能重复投递。用 event.id 做幂等键,处理过的直接返回 200。
第 4 步:定时对账兜底
下面是完整可运行的 Python 实现:
import hmac, hashlib, time, requests
API_BASE = "https://api.thiskard.com"
WEBHOOK_SECRET = "whsec_xxx"
API_KEY = "sk_live_xxx"
def verify_signature(payload_body: bytes, signature: str) -> bool:
expected = hmac.new(
WEBHOOK_SECRET.encode(), payload_body, hashlib.sha256
).hexdigest()
return hmac.compare_digest(expected, signature)
processed_event_ids = set() # 生产环境请用 Redis/DB
def handle_webhook(payload: dict, signature: str, raw: bytes):
if not verify_signature(raw, signature):
return {"status": "rejected"}, 401
if payload["id"] in processed_event_ids:
return {"status": "duplicate"}, 200 # 幂等:重复事件直接确认
event_type = payload["type"]
fx = payload["data"]
order_id = fx["order_id"]
if event_type == "fx.settled":
# 与内部预期金额比对,写合规USD账本
mark_settled(order_id, fx["usd_amount"], fx["tx_hash"])
elif event_type in ("fx.failed", "fx.flagged"):
flag_for_review(order_id, event_type)
processed_event_ids.add(payload["id"])
return {"status": "ok"}, 200
def reconcile(since_minutes: int = 15):
"""主动对账:拉取窗口期内已结算订单,补齐漏掉的通知"""
headers = {"Authorization": f"Bearer {API_KEY}"}
params = {
"settled_since": int(time.time()) - since_minutes * 60,
"limit": 200,
}
resp = requests.get(
f"{API_BASE}/v1/fx/orders", headers=headers,
params=params, timeout=10,
)
resp.raise_for_status()
for order in resp.json()["data"]:
local = get_local_order(order["order_id"])
if local is None:
continue # 非本系统发起,跳过
if local["status"] != "settled" and order["status"] == "settled":
mark_settled(
order["order_id"],
order["usd_amount"], order["tx_hash"],
)
alert_ops(f"对账补单: {order['order_id']}")
def mark_settled(order_id, usd_amount, tx_hash):
# TODO: 数据库事务中更新状态 + 写入审计日志
pass
def flag_for_review(order_id, event_type): pass
def get_local_order(order_id): return {"status": "pending"}
def alert_ops(msg): print("[ALERT]", msg)
if __name__ == "__main__":
# 由 celery beat / cron 每 5 分钟调度
reconcile(since_minutes=10)
第 5 步:金额校验与告警
对账补单时务必核对三样东西:定锚汇率、USD 入账金额、链上 tx_hash。金额与本地预期偏差超过滑点容忍度(建议 basis 级配置)时,不要自动入账,转人工复核——这正是机构风控对冲流程里“系统发现问题、人做最终裁决”的边界设计。
错误处理与最佳实践
- 回调必须快速返回 200,重业务逻辑放到队列异步处理,否则 OnyxClearing 会判定投递失败并重试,加剧堆积
- 重试风暴防护:OnyxClearing 对 5xx 会指数退避重试,端点持续故障时先降级为“仅对账模式"
- 时间窗口重叠:对账查询窗口故意大于调度间隔(如 10 分钟窗口、5 分钟调度),避免边界漏单;幂等键保证重复处理无害
- 密钥隔离:webhook secret 与 API key 分开存放,验证逻辑用恒定时间比较(如上
hmac.compare_digest) - 审计留痕:所有对账补单写入不可变日志,配合渐进式 KYB 审计要求留存至少 180 天
- 沙盒先行:先用 thiskard.com/developers 的沙盒环境模拟事件丢失、重复投递、金额异常三种场景,再上生产
结语
Webhook 会丢,但账不能丢。把通知当作“提示”而非“事实”,用主动对账兜底、签名验证防伪、幂等设计防重,你的换汇管道就能达到机构级的可靠性标准——无论交易规模多大,合规USD账本始终分毫不差。
准备好开始构建了吗?访问 thiskard.com/developers 获取API文档、SDK和沙盒环境。