SuperAPI AI 工具集

aftership-webhooks

测试与质量

查看项目

更新于 10-15 22:14

技能介绍

用途:帮助开发者搭建 AfterShip Webhook 接收端,并正确校验签名。AfterShip 的 Tracking、Shipping(原 Postmen)、Returns、Warranty 四个产品都会发送 Webhook,使用同一套 HMAC 算法,但签名放在三个不同的请求头中。

主要能力:统一校验逻辑——对原始请求体做 HMAC-SHA256,密钥为 Webhook secret 的 UTF-8 字符串(不要 base64 解码),摘要用标准 base64 编码。签名头分别为:Tracking 用 aftership-hmac-sha256,Returns/Warranty 用 as-signature-hmac-sha256(均为裸 base64),Shipping 及旧版 Returns 用 am-webhook-signature(格式 hmac-sha256=<base64>)。没有时间戳头,也没有重放窗口,因此不要加容差检查。

使用方式:必须使用原始请求体(如 express.raw、Next.js 的 await req.text()、FastAPI 的 await request.body()),重新序列化会破坏签名。每个产品有各自的 secret,需按产品分别配置端点。示例代码见 examples/express、examples/nextjs、examples/fastapi。本地调试可用 npx hookdeck-cli listen 3000 aftership --path /webhooks/aftership。

事件类型:Tracking 仅有 tracking_update、edd_revise、tracking_pending_time 三种,状态在 msg.tag/msg.subtag 中,需按 tag 路由;Shipping 事件名在 event_type;Returns 与 Warranty 各有独立事件列表。

限制:官方 Node SDK 无 Webhook 校验辅助,需手动实现。响应需返回 2xx,否则 AfterShip 最多重试 14 次(指数退避,约 68 小时)。Tracking Webhook URL 必须使用 80、443 或 8080 端口,每个组织最多注册 10 个。无握手或挑战机制。