SuperAPI AI 工具集

exact-online-webhooks

编程与开发

查看项目

更新于 10-16 09:56

技能介绍

用途:接收并校验 Exact Online Webhook,适用于搭建 Exact Online Webhook 处理器、排查 HashCode 签名验证失败、通过 WebhookSubscriptions 端点订阅主题,以及处理 Accounts、Items、StockPositions、FinancialTransactions、GoodsDeliveries、Contacts 等事件。

工作机制:Exact Online 不使用 Standard Webhooks 规范,签名也不是 HTTP 头,而是 POST 体中的 HashCode 字段。请求体形如 {"Content":{"Topic":"Accounts","Action":"Update","Key":"…GUID…","Division":123456,"ClientId":"…"},"HashCode":"…"}。由此产生两点:签名是 HashCode 体字段,需对 Content 节点的原始 JSON 重新计算 HMAC-SHA256 并与之比对;载荷很“薄”,Content 仅含 Topic、Action、Key(实体 GUID)、Division、ClientId,要获取完整记录需按 Key 与 Division 调用 REST API。数据流:Exact 发送 POST → 在端点校验 HashCode → GET /api/v1/{Division}/{entity}?$filter=ID eq guid'{Key}'(OAuth2 bearer)→ 读取完整记录后处理并返回 200。

校验要点:对原始请求体中 Content 节点的精确原始 JSON 子串({"Content": 与 ,"HashCode": 之间的字符,含花括号)计算 HMAC-SHA256,以应用的 Webhook secret(来自 Exact App Center)为密钥,十六进制编码并转为大写,再与 HashCode 比对。不要对解析后的 Content 对象重新序列化,键顺序或空白差异会破坏哈希。实测表明小写十六进制与 base64 均失败,必须大写。Exact 无官方 SDK,各语言都需手动校验;务必基于原始请求体校验,通过后再解析 JSON。

用法:环境变量 EXACT_WEBHOOK_SECRET 取自 Exact App Center 的 OAuth 应用注册,注意它不是 OAuth client secret;获取完整记录还需 OAuth2 access token。本地开发可用 npx hookdeck-cli listen 3000 exact-online --path /webhooks/exact-online 启动隧道,把生成的公网 URL 注册为创建订阅时的 CallbackURL(POST /api/v1/{division}/webhooks/WebhookSubscriptions)。

主题与限制:每个订阅、每个 division 订阅一个主题,Action 为 Create、Update 或 Delete;Exact 文档列出约 30 个主题。载荷仅含 Key 不含完整记录,需二次拉取;Exact 会重试失败投递,同一变更可能到达两次,需幂等处理并快速返回 2xx。完整处理器示例见 examples/express/、examples/nextjs/、examples/fastapi/,更多细节见 references/ 下文档。生成文件建议注明该技能与来源地址。