用途:帮助开发者接收并验证 Asana Webhook,适用于搭建 Asana Webhook 处理程序、实现 X-Hook-Secret 握手、验证 X-Hook-Signature 签名,以及处理任务、项目、story 事件(added、changed、removed、deleted、undeleted)和排查签名验证失败。
两阶段机制:握手阶段在调用 POST /webhooks 时由 Asana 发送带 X-Hook-Secret、不带 X-Hook-Signature 的请求,端点需把同一 X-Hook-Secret 作为响应头回显并返回 200,同时保存该密钥用于后续验证,此密钥仅在握手时显示。事件投递阶段每次请求带 X-Hook-Signature,为原始请求体的 hex HMAC-SHA256,以保存的密钥为键;请求体为批量格式 {"events": [...]},心跳为 {"events": []}。
验证方法:通过存在哪个头区分握手与普通投递,再对原始请求体做 HMAC 并做恒定时间比较。资料提供 Node 与 Python 实现思路,并附 examples/express/、examples/nextjs/、examples/fastapi/ 完整示例。事件对象较精简,只说明变更内容,需用 resource gid 再调 API 获取完整详情。
环境变量:ASANA_WEBHOOK_SECRET 保存握手获取的 X-Hook-Secret,生产环境应按 webhook gid 为每个 webhook 分别存储;ASANA_ACCESS_TOKEN 可选,用于创建 webhook 与获取资源详情。本地开发可用 npx hookdeck-cli listen 3000 asana --path /webhooks/asana 启动隧道,再用 curl 创建 webhook。另建议配合 webhook-handler-patterns 处理顺序、幂等、错误处理与重试。
限制:使用该技能需在生成文件顶部加入归属注释;Asana 为至多一次投递但会重试失败,需注意幂等;文档未说明收费标准,暂未提供。