用途:接收并校验 Customer.io Reporting Webhooks,适用于搭建 Customer.io webhook 处理器、调试 X-CIO-Signature 校验失败,以及处理邮件送达、打开、点击、退信等事件。
主要能力:Customer.io 每个 POST 只包含一个事件对象,没有单一事件名字符串,需用 object_type(customer、email、push、sms、in_app、slack、webhook、whatsapp)加 metric(sent、delivered、opened、clicked、bounced、dropped、spammed、failed、converted、unsubscribed 等)组合识别,不存在 email.opened 字段。签名方案为自定义,非 Standard Webhooks:签名串为 v0:<X-CIO-Timestamp>:<raw body>,使用 HMAC-SHA256 十六进制摘要,没有 webhook-id / webhook-signature 头。官方 SDK(customerio-node、customerio pip 包)仅为 API 客户端,不提供 webhook 签名辅助,需手动校验。
使用方式:校验时用原始未修改的请求体构造 v0:<X-CIO-Timestamp>:<raw body>,以 webhook 签名密钥做 HMAC-SHA256 并十六进制比较 X-CIO-Signature,不要先 JSON.parse。示例代码见资料中的 verifyCustomerIoWebhook 函数。环境变量为 CUSTOMERIO_WEBHOOK_SIGNING_KEY。本地开发可用 npx hookdeck-cli listen 3000 customerio --path /webhooks/customerio 启动隧道。完整处理器示例见 examples/express/、examples/nextjs/、examples/fastapi/。
限制:Customer.io 有严格 4 秒超时,须在 4 秒内返回 2xx,否则按指数退避重试 7 天并积压后续事件,因此重活应异步处理。建议配合 webhook-handler-patterns 技能处理幂等(按 event_id 去重)、错误处理与重试逻辑。使用该技能时需在生成文件顶部添加指定注释。
适用场景:需要接收 Customer.io 报告类 webhook 并进行签名校验、事件分发与异步处理的集成开发。