SuperAPI AI 工具集

utila-webhooks

编程与开发

查看项目

更新于 10-16 05:52

技能介绍

Utila 是数字资产运营平台。其 Webhook 会在交易和钱包状态变化时通知你的端点,便于与 Utila API 对账。验证采用非对称 RSA 而非 HMAC,不共享密钥。

用途:接收 Utila Webhook、校验 x-utila-signature、排查签名验证失败、处理交易与钱包相关事件、在 Utila Console 中配置 Webhook。

验证方式:Utila 使用 RSA-4096 私钥、SHA-512 与 PSS 填充签名,base64 编码后放在 x-utila-signature 头。你用从 Console(Vault Settings → Webhooks)复制的 PEM 编码 RSA-4096 公钥验证。要点:无共享密钥、无 HMAC;非 Standard Webhooks,无 webhook-id / webhook-timestamp 头;无时间戳头,无内置重放保护,需按事件 id 去重并保证幂等;必须对原始请求体字节验证,且在 JSON 解析前进行。核心验证可参考资料中的 crypto.verify 示例(注意 rawBody 为原始 Buffer,padding 使用 RSA_PKCS1_PSS_PADDING)。完整处理器与测试见 examples/express/、examples/nextjs/、examples/fastapi/。

事件类型共五种(SCREAMING_SNAKE_CASE,位于 payload 的 type 字段):TRANSACTION_CREATED、TRANSACTION_STATE_UPDATED、WALLET_CREATED、WALLET_ADDRESS_CREATED、TRANSACTION_AML_SCREENING_RESULT_READY。载荷较薄,只含标识符(id、vault、type、resourceType、resource、可选 details),需用 resource 路径从 Utila API / Stream 获取完整对象。完整载荷见 references/overview.md。

环境变量:UTILA_WEBHOOK_PUBLIC_KEY,为 Utila 的 PEM RSA-4096 公钥。PEM 为多行,可存为真实多行或使用转义 \n。SDK 说明:Utila 文档提及 npm 包 @utila/api,但当前公共 registry 无法解析,且无 Python SDK,示例使用平台加密库手动验证。

本地开发可用 Hookdeck CLI:npx hookdeck-cli listen 3000 utila --path /webhooks/utila。无需账号,首次运行创建访客账户并提供本地隧道与检查界面。建议搭配 webhook-handler-patterns 处理幂等、错误处理与重试。相关技能包括 circle-webhooks、fireblocks-webhooks、bridge-xyz-webhooks、zerohash-webhooks、hookdeck-event-gateway。