用途:接收并校验 Upollo 风控平台的 webhook,在风控标记用户时触发相应处理。Upollo 属于欺诈/风险检测平台,其 webhook 不是按命名事件订阅,而是在标记用户(如账号共享、多账号)时推送一份分析结果,包含用户、设备、建议动作和触发的标记列表。
主要能力:每次推送都带签名,Upollo 用 webhook 密钥对原始请求体计算 HMAC-SHA512,放入 Upollo-Signature 头。它不使用 Standard Webhooks 方案,仅用单个头,含 t: 与 s0: 两部分:t 为投递的 Unix 秒级时间戳,可用于可选的防重放,不参与签名内容;s0 为 HMAC-SHA512(secret, rawBody)。摘要编码官方未说明是 hex 还是 base64,s0: 前缀与观察到的 128 字符值提示为小写 hex;示例代码同时接受 hex 或 base64。
使用方式:先对原始请求体校验签名,再解析。签名头形如 Upollo-Signature: t:1706352000,s0:3f9a...<128 hex chars>,用时间安全比较。由于没有事件名,应按载荷中的 action 与 flags 数组分发。action 取值(短形式)包括 PERMIT、CHALLENGE、OFFER、DENY、LOG,分别对应放行、触发多因素验证、展示升级/优惠、拦截、仅记录。flags[].type 常见值包括 ACCOUNT_SHARING、ACCOUNT_SHARING_SAME_HOUSEHOLD、MULTIPLE_ACCOUNTS、REPEATED_SIGNUP、TRIALED_ON_OTHER_ACCOUNT、REPEATED_REDEMPTION、SUSPECTED_FRAUD、SUSPECTED_BOT、SUSPECTED_ACCOUNT_COMPROMISE、CREDENTIAL_STUFFING、USING_VPN、USING_TOR、DISPOSABLE_EMAIL 等。源枚举带前缀(OUTCOME_CHALLENGE、EVENT_TYPE_LOGIN、FLAG_TYPE_UNSPECIFIED),实际载荷用短形式,示例处理会剥离前缀以兼容两种形式。环境变量为 UPOLLO_WEBHOOK_SECRET,需在 app.upollo.ai 的 Access & Keys 页面添加 webhook URL 时生成。本地开发可用 npx hookdeck-cli listen 3000 upollo --path /webhooks/upollo 建立隧道。测试标记可用带后缀邮箱,如 you+account_sharing@example.com 触发 ACCOUNT_SHARING,you+multiple_accounts@example.com 触发 MULTIPLE_ACCOUNTS。
适用场景:设置 Upollo webhook 处理器、调试签名校验失败、对 ACCOUNT_SHARING、MULTIPLE_ACCOUNTS 等标记做出响应、处理 CHALLENGE/DENY/PERMIT/OFFER/LOG 动作。
限制:截至资料撰写时,app.upollo.ai / upollo.ai 无法解析,npm 包 @upollo/web 与 @upollo/node 返回 404(PyPI 的 upollo-python 仍发布),Upollo 可能已下线或易主;依赖此集成前需确认其可用性,并针对真实投递重新验证签名方案与载荷。本文档的校验方案与 Upollo 自身的 protobuf 定义一致,但未在真实载荷上确认。生成文件时需按资料要求在顶部添加注释:// Generated with: upollo-webhooks skill 与 // https://github.com/hookdeck/webhook-skills。建议同时安装 webhook-handler-patterns 技能以处理处理顺序、幂等、错误处理与重试逻辑。