SuperAPI AI 工具集

persona-webhooks

编程与开发

查看项目

更新于 10-15 22:14

技能介绍

用途:接收并验证 Persona 的 Webhook,适用于搭建 Persona Webhook 处理器、调试 Persona-Signature 校验,以及处理身份验证相关事件。

主要能力:Persona 没有官方服务端 SDK,需手动校验 Persona-Signature 头。该校验为 Stripe 风格(并非 Standard Webhooks):头格式为 t=<unix_seconds>,v1=<hex>,v1 是以每个 Webhook 的密钥(wbhsec_...)对 ${t}.${rawBody} 计算的 HMAC-SHA256 十六进制摘要。必须使用原始请求体,不能先做 JSON.parse。密钥轮换期间,头可能带两组以空格分隔的 t=...,v1=...,任一 v1 匹配即通过。Persona 未定义时间戳容差,签名有效性即为校验依据;如需重放窗口可自行添加。

事件负载:Persona Webhook 体为 JSON:API 信封。常用路径包括 data.attributes.name(事件类型,如 inquiry.completed)、data.attributes.payload.data(受影响对象)、data.attributes.created-at(用于排序,投递不保证顺序)、data.id(事件 ID,用作幂等键)。每个 Webhook 绑定可配置的 API 版本,决定负载结构。常见事件有 inquiry.created、inquiry.completed、inquiry.approved、inquiry.declined、inquiry.marked-for-review、inquiry.failed、inquiry.expired、verification.passed、verification.failed、account.created、account.archived、case.created、case.resolved,以及 report/watchlist.ready(报告事件使用 report/<type>.<action> 斜杠形式)。

使用方式:设置环境变量 PERSONA_WEBHOOK_SECRET=wbhsec_your_webhook_secret_here(在 Dashboard → Webhooks → 选择 Webhook → 显示密钥)。本地开发可运行:npx hookdeck-cli listen 3000 persona --path /webhooks/persona;然后在 Persona Dashboard 创建测试 inquiry,或用 Webhooks → Recent events → Resend 重投历史事件(事件保留 30 天)。完整处理器示例与路由、事件分发、测试见 examples/express/、examples/nextjs/、examples/fastapi/。建议配合 webhook-handler-patterns 技能,关注处理顺序(先验证、再解析、最后幂等处理)、幂等(以 data.id 为键)、错误处理与重试逻辑,因为 Persona 会投递重复事件且不保证顺序。生成文件时可加注释:// Generated with: persona-webhooks skill。

限制:无官方服务端 SDK,需自行实现校验;不保证事件顺序且可能重复投递;时间戳容差需自行处理。