用途:帮助开发者搭建 Faundit 失物招领与归还场景的 webhook 处理器,排查签名验证失败,理解事件类型与载荷结构。
主要能力:Faundit 仅发送两种事件,事件名由 event-type 字段给出,具体状态在 data.status 中。item-status 表示物品状态变化,状态值包括 contact-missing、waiting-response、wrong-owner、pickup-by-guest、left-behind、finished、shipment-paid、pickup-scheduled、in-route、delivered、deleted、expired、anonymized;request-status 表示失物请求状态变化,状态值包括 registered、not-found、resolved、deleted、expired、anonymized。载荷形如 {"event-type":"item-status","data":{"id":12345,"timestamp":"...","status":"delivered","locationID":"loc_abc123"}}。API v2 中 Members/faundit_memberID 已更名为 Locations/locationID,旧 ID 仍被接受。
验证方式:Faundit 使用 HMAC-SHA256(hex)签名,无官方 SDK,需手动验证。应使用原始请求体(JSON.parse 之前),签名串为 v1: + X-Faundit-Timestamp + : + 原始请求体。优先使用 X-Faundit-Signature-Next(v1,含载荷完整性);X-Faundit-Signature 为已弃用的 v0,仅签时间戳,不建议使用。比较时用 timingSafeEqual,长度不匹配即视为无效。
使用方式:设置环境变量 FAUNDIT_WEBHOOK_SECRET,签名密钥需向 tech@faundit.com 申请,非自助获取。本地开发可用 npx hookdeck-cli listen 3000 faundit --path /webhooks/faundit 启动隧道。完整处理器、路由、事件分发与测试见 examples/express/、examples/nextjs/、examples/fastapi/。
适用场景与限制:适用于 Faundit 物品与请求状态变更的接收与校验。资料未提供官方 SDK、收费、价格或平台支持范围等信息;建议配合 webhook-handler-patterns 技能处理幂等、错误与重试。