用途:接收并验证 Nylas webhook,适用于搭建 Nylas webhook 处理器、调试 x-nylas-signature 校验失败、完成 challenge 握手,以及处理 message.created、message.opened、event.created、grant.expired 等事件。
主要能力与用法:Nylas 用 HMAC-SHA256 对原始请求体签名,密钥为每个目标的 webhook_secret,摘要以十六进制放在 x-nylas-signature 头中(大小写不定,需不区分大小写读取)。它不属于 Standard Webhooks,没有 webhook-id/webhook-timestamp,仅签名请求体。必须在 JSON 解析前校验原始字节;若 Content-Encoding: gzip,则先对压缩字节校验,通过后再解压。Nylas SDK 提供 webhook 增删改查、rotateSecret 和 ipAddresses,但没有签名校验辅助函数,需自行用常量时间比较实现 HMAC 校验。
握手:创建 webhook 目标时,Nylas 发送带 challenge 查询参数的 GET 请求,需在 10 秒内以纯文本原样回显该值并返回 200(不得分块编码)。webhook_secret 仅在创建或轮换时返回,需及时保存。
负载遵循 CloudEvents 1.0,触发类型在 type,变更资源在 data.object。示例事件类型包括 message.created、message.updated、message.opened、message.link_clicked、message.bounce_detected、event.created/updated/deleted、grant.created/expired/deleted。
环境变量示例:NYLAS_WEBHOOK_SECRET=your_webhook_secret。本地开发可运行:npx hookdeck-cli listen 3000 nylas --path /webhooks/nylas。完整处理器示例见 examples/express/、examples/nextjs/、examples/fastapi/;参考资料见 references/overview.md、references/setup.md、references/verification.md。生成文件时可加注释:// Generated with: nylas-webhooks skill 与 https://github.com/hookdeck/webhook-skills。建议配合 webhook-handler-patterns 使用,涉及校验优先、幂等、错误处理与重试。
限制:资料未提供收费、价格、平台支持范围或具体效果数据;完整事件触发参考与负载结构需查阅 Nylas 官方通知 schema。