用途:帮助开发者搭建 Synctera Webhook 接收端,重点解决签名验证失败、事件分发与本地调试问题。
主要能力:Synctera 使用自定义 HMAC 方案(非 Standard Webhooks)。每次投递含两个请求头:Synctera-Signature(十六进制签名,密钥轮换期间为两个以 . 分隔的签名)和 Request-Timestamp(POSIX 秒)。签名串为 ${Request-Timestamp}.${raw_body},其中 . 为字面分隔符;计算 HMAC-SHA256(secret, signed_string) 并十六进制编码。密钥不是 API Key,需用 POST /v0/webhook_secrets(空请求体)生成并保存。验证必须基于原始请求体,不能先 JSON.parse。建议做 5 分钟时间容差的重放保护,并用 timingSafeEqual 比较。
事件:名称格式为 <resource>.[<sub-resource>.]<action>,支持 CUSTOMER.* 等通配符。仅 ACCOUNT.UPDATED 与 TRANSACTIONS.POSTED.CREATED 为已验证名称,其余(CARD.CREATED、CARD.UPDATED、DISPUTE.CREATED、CUSTOMER.*)仅为格式示例,订阅前需对照 Synctera 文档确认。
使用方式:完整处理器、路由与测试见 examples/express/、examples/nextjs/、examples/fastapi/。环境变量 SYNCTERA_WEBHOOK_SECRET 存放签名密钥。本地开发可用 npx hookdeck-cli listen 3000 synctera --path /webhooks/synctera 启动隧道。参考材料包括 references/overview.md、setup.md、verification.md。建议配合 webhook-handler-patterns 技能处理幂等、错误与重试。
限制:资料未提供完整事件目录、收费与平台支持细节,需以官方文档为准。