WhatsApp Passkey 二维码认证：安全接入 Webhook 的操作指南

WhatsApp 二维码配对过程中可能会要求 Passkey 身份确认。看到 passkey_required 时，不要重建账号，也不要创建第二个 WhatsApp 连接；应继续同一个认证会话，让账号持有人完成浏览器里的 WebAuthn 凭证确认，再把凭证响应提交给 UnifyPort，等待 authorized 以及后续签名 Webhook 事件。

关键结论

• WhatsApp 官方帮助中心说明，Passkey 会把账号与手机的安全系统关联，例如指纹、面容或屏幕锁，用于身份验证。
• WhatsApp Business 的已连设备流程既支持扫描二维码，也支持输入 8 位代码；两种路径都可能要求在主手机上确认身份。
• 在 UnifyPort 中，Passkey 是 WhatsApp QR 认证的继续状态：passkey_required → passkey_pending → 可选的 passkey_confirmation → authorized。
• 先注册 Webhook，再做认证，这样不会漏掉 account.auth.required、account.auth.succeeded 和之后的 message.received。
• 如果你的接收端还没准备好，先看Webhook 优先的入站接入清单，签名排查时可配合HMAC 重放保护教程。

WhatsApp 实际要求的是什么

这不是新的消息 API 凭证，而是 WhatsApp 账号访问过程中的身份确认步骤。

WhatsApp 官方 Passkey 文档说明，Passkey 使用设备安全系统，并可在 WhatsApp 需要确认身份时使用。官方已连设备文档也说明了二维码和手机号代码两种 WhatsApp Business 配对方式，包括用生物识别或手机解锁 PIN 确认身份。因此，当 UnifyPort 的二维码流程进入 Passkey 分支时，应把它当作需要用户参与的认证仪式，而不是服务端可以自行生成的密钥。

这个边界很重要：后端负责保存 UnifyPort 消息账号状态和 Webhook 接收端；账号持有人负责在浏览器或已授权手机上完成 WebAuthn 提示。日志里不要保存完整的 authorize_url、auth_payload.public_key 或序列化凭证响应。

UnifyPort 流程

实现时可同时打开Create provider authorization session 和 Submit Passkey credential response。核心状态如下：

状态	含义	应做动作
awaiting_qr_scan	二维码有效	展示给账号持有人，并轮询 GET /v1/accounts/{account_id}/auth 或 POST /v1/accounts/{account_id}/auth/qr/check。
passkey_required	WhatsApp 需要 WebAuthn 凭证	打开托管的 authorize_url，让持有人完成浏览器凭证提示。
passkey_pending	凭证已提交	继续轮询认证状态，不要启动新流程。
passkey_confirmation	WhatsApp 需要额外确认	持有人确认后调用 POST /v1/accounts/{account_id}/auth/passkey-confirm。
authorized	认证完成	runtime 通常会自动启动；观察 account.auth.succeeded 和 account.started。

第一步：先创建 Webhook

curl -X POST https://api.unifyport.ai/v1/webhook-endpoints \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://ops.example.com/unifyport/webhook",
  "status": "active",
  "subscribed_events": ["account.auth.required", "account.auth.succeeded", "message.received"],
  "signing_secret": "stored-in-your-secret-manager",
  "retry_policy": { "max_attempts": 3 }
}'

生产接收端必须先用原始请求体校验 X-Device-Signature。完整签名规则见Webhook delivery 文档：HMAC-SHA256 输入是 X-Device-Timestamp + "." + raw request body。

第二步：创建 WhatsApp 消息账号

curl -X POST https://api.unifyport.ai/v1/accounts \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "WhatsApp Support Passkey Test",
  "provider": "whatsapp",
  "region": "global",
  "status": "active",
  "auth_mode": "qrcode",
  "capabilities": ["send_message", "receive_message"],
  "provider_data": { "device_os": "Chrome", "device_platform": "web" },
  "metadata": { "environment": "staging" }
}'

保存返回的 account_id。账号对象会暴露 runtime_status；认证状态和二维码、Passkey 负载则通过独立认证接口读取。

第三步：启动二维码认证并继续 Passkey

curl -X POST https://api.unifyport.ai/v1/accounts/acc_whatsapp_passkey_test/auth-sessions \
  -H "X-Api-Key: $UNIFYPORT_API_KEY"

如果响应或后续检查进入 passkey_required，就把 authorize_url 交给账号持有人打开。浏览器会生成 WebAuthn 凭证响应，再由你的可信认证交接层提交到 POST /v1/accounts/{account_id}/auth/passkey-response。若状态变成 passkey_confirmation，确认后调用 /auth/passkey-confirm，然后轮询 /auth，直到 authorized 或 failed。

第四步：验证第一条入站事件

认证成功后，通常会先收到账号事件，随后收到普通入站消息：

{
  "id": "evt_2f9c1a4b7e",
  "type": "message.received",
  "provider": "whatsapp",
  "account_id": "acc_whatsapp_passkey_test",
  "occurred_at": "2026-09-10T08:15:21Z",
  "data": {
    "conversation": { "id": "8613912345678@s.whatsapp.net", "type": "user" },
    "sender": { "id": "8613912345678@s.whatsapp.net", "type": "user", "name": "Jordan Lee" },
    "message": { "id": "wamid.HBgM", "text": "Can you confirm my order?", "direction": "inbound", "sent_at": "2026-09-10T08:15:20Z" },
    "event": { "kind": "message_received" }
  }
}

从这里开始，Passkey 分支已经结束。后续按普通 WhatsApp 入站流程存储和路由即可。若你还在设计整体接入，可对照连接 Telegram 用户账号到 Webhook以及首次 API Key Webhook 测试清单。

限制与取舍

如果你需要官方企业身份、模板、官方分析或 Meta 的完整政策面，应选择 WhatsApp Business Platform。若目标只是把现有普通 WhatsApp 收件箱接入一个签名 Webhook，UnifyPort 的非官方接口更适合小团队快速落地。

Passkey 不会取消用户确认步骤。它只是把该步骤清晰地放进运行手册：用户完成凭证提示，服务端不记录敏感认证数据，Webhook 在账号上线前已经准备好。

FAQ

passkey_required 是错误吗？

不是。它是 WhatsApp QR 认证中的正常继续状态。继续当前会话并提交浏览器生成的凭证响应。

QR 进入 Passkey 后要不要新建账号？

不要。新建账号可能造成重复 provider 身份冲突。应继续轮询当前认证状态。

应该保存哪些数据？

保存 account_id、认证状态、Webhook 事件 ID 和收到的消息。不要把完整授权 URL 或序列化 WebAuthn 凭证写入日志。

2026-09-10 核对来源

• WhatsApp Help Center: About passkeys
• WhatsApp Help Center: How to link a device with QR code on the WhatsApp Business app
• WhatsApp Help Center: How to link a device using a phone number and the WhatsApp Business app
• Google for Developers: Passkeys developer guide for relying parties