← Blog & Resources

อย่าตกใจถ้าการแจ้งเตือนแลกเปลี่ยนเงินสูญหาย - สร้างระบบกระทบยอดแลกเปลี่ยนอัตโนมัติระดับสถาบันด้วย 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 只当加速器,不当唯一事实来源,配一套定时对账兜底。

整体架构:三层防线

  1. Webhook 实时层:换汇完成立即收到事件,更新本地订单状态
  2. 签名验证层:防止伪造回调污染你的合规USD账本
  3. 主动对账层:定时调用 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和沙盒环境。