SuperAPI AI 工具集

onfleet-webhooks

编程与开发

查看项目

更新于 10-17 13:48

技能介绍

用途

onfleet-webhooks 面向需要接收 Onfleet 末端配送平台 Webhook 的开发者,提供处理器搭建、URL 校验握手、签名验证与调试的完整指引。每个 Onfleet Webhook 只针对一个触发事件,例如 taskStarted、taskCompleted、workerDuty 等。

主要能力

  1. 校验握手:创建 Webhook 时,Onfleet 发送 GET <你的URL>?check=<随机字符串>,需以 200 状态码和纯文本响应原样返回该字符串;该请求不带签名,且不接受 204。
  2. 签名验证:事件以签名 POST 送达,头为 X-Onfleet-Signature,算法为 HMAC-SHA512、hex 摘要,密钥为组织 Webhook secret 的十六进制解码字节,签名内容为原始请求体字节,无时间戳和前缀。资料给出 Node.js 与 Python 实现,并提醒直接用字符串作 HMAC 密钥会导致摘要永不匹配。
  3. 触发事件清单:资料列出 taskStarted、taskEta、taskCompleted、taskFailed、workerDuty 等事件的 triggerId/triggerName,并说明 ID 11 与 21 未记录,触发器 30 存在 predictedTaskDelay 与 taskPredictedDelay 命名差异。
  4. 处理器规则:先验证原始字节再解析、10 秒内响应、字段均可能为 null、注意毫秒与秒单位、未知触发器记录后返回 200。
  5. 示例与参考:examples/express/、examples/nextjs/、examples/fastapi/ 提供含测试的完整处理器;references/overview.md、setup.md、verification.md 分别覆盖触发与载荷、密钥与创建方式、HMAC 细节与调试。

使用方式

设置环境变量 ONFLEET_WEBHOOK_SECRET 为十六进制 Webhook 密钥(可在仪表盘 Configuration -> API & Webhook -> Show Secret 查看)。本地开发可用 npx hookdeck-cli listen 3000 onfleet --path /webhooks/onfleet 启动隧道,并先运行处理器以使握手成功。使用该技能时需在生成文件顶部添加来源注释。

适用场景

适用于构建 Onfleet 配送任务状态、路线计划、配送员状态等事件的接收端点,以及排查 Webhook URL 无法保存、签名不匹配等问题。

限制

资料未提供具体的收费、价格、平台支持范围或性能指标;Onfleet 重试与禁用策略等事实以资料所述为准。