用途:接收并验证 Attentive 的 Webhook 请求,适用于搭建 Attentive Webhook 处理程序、排查 x-attentive-hmac-sha256 签名校验失败,以及处理 sms.subscribed、sms.unsubscribed、email.opened 等事件和解析事件类型与载荷。
主要能力:Attentive 使用每个 Webhook 的签名密钥(仪表板中称为 client secret)对原始请求体做 HMAC-SHA256,结果以十六进制放在 x-attentive-hmac-sha256 请求头中。签名不含时间戳,不使用 Standard Webhooks 方案;官方无服务端 SDK,需手动验证。技能提供 Node 与 Python 的校验函数:Node 用 crypto.createHmac('sha256', secret).update(rawBody).digest('hex') 后做 timingSafeEqual 比较;Python 用 hmac.new(secret.encode('utf-8'), raw_body, hashlib.sha256).hexdigest() 配合 hmac.compare_digest。技能内含 express、nextjs、fastapi 完整处理示例(含路由、事件分发与测试)。
使用方式:对精确的原始请求体计算 HMAC,进行时序安全比较。事件名在载荷的 type 字段中(Attentive 不发送事件类型头,仅签名头)。常见事件包括 sms.subscribed、sms.unsubscribed、sms.sent、sms.inbound_message、sms.message_link_click、email.subscribed、email.unsubscribed、email.sent、email.opened、email.message_link_click、custom_attribute.set。载荷含 type、timestamp(Unix 毫秒)、company.id 与 subscriber 字段,subscriber 下字段随事件类型不同。环境变量为 ATTENTIVE_WEBHOOK_SECRET=your_signing_key。本地开发可运行:npx hookdeck-cli listen 3000 attentive --path /webhooks/attentive。
适用场景与限制:适合需要接入 Attentive 短信与邮件事件的应用。Attentive 对失败投递按指数退避重试,最长约 3 天,且不保证事件顺序,因此应做幂等处理;建议搭配 webhook-handler-patterns 技能(先验证、再解析、再幂等处理)。生成文件时按要求添加注释来源。需注意签名失败常见原因是未使用原始请求体或比较方式不安全。