WhatsApp Passkey QR 認證：安全完成 Webhook 接入

WhatsApp QR 配對有時會要求 Passkey 身分確認。若認證狀態變成 passkey_required，不要重建帳號，也不要開第二條 WhatsApp 連線；應繼續同一個認證工作階段，讓帳號持有人完成瀏覽器中的 WebAuthn 憑證提示，再把回應提交給 UnifyPort，等待 authorized 以及後續簽名 Webhook 事件。

重點整理

• WhatsApp 官方說明指出，Passkey 會把帳號與裝置安全系統連結，例如指紋、臉部辨識或螢幕鎖，用於確認身分。
• WhatsApp Business 的 linked-device 流程支援 QR code 與 8 字元電話號碼代碼；兩者都可能要求在主要手機上確認身分。
• 在 UnifyPort 中，Passkey 是 WhatsApp QR 認證的延續狀態：passkey_required → passkey_pending → 可選的 passkey_confirmation → authorized。
• 先註冊 Webhook，再進行認證，才不會錯過 account.auth.required、account.auth.succeeded 與後續 message.received。
• 如果接收端還沒完成，先看 webhook-first inbound checklist；簽名與重放保護可參考 HMAC replay protection guide。

WhatsApp 要求的是哪一層認證？

這不是新的訊息 API credential，而是 WhatsApp 帳號存取流程中的使用者身分確認。

WhatsApp 的 Passkey 說明指出，Passkey 使用裝置安全系統，並可在 WhatsApp 需要驗證身分時使用。官方 linked-device 文件也說明 WhatsApp Business 可以用 QR code 或電話號碼代碼配對，並可能要求使用生物辨識或手機解鎖 PIN 確認。因此，當 UnifyPort QR 流程進入 Passkey 分支時，請把它視為需要使用者參與的認證流程，而不是後端可以自行產生的 secret。

後端應保存 UnifyPort messaging account 狀態與 Webhook 接收端；帳號持有人應在瀏覽器或已授權手機上完成 WebAuthn 提示。請勿在 log 中保存完整 authorize_url、auth_payload.public_key 或序列化 credential response。

UnifyPort 流程

請搭配 Create provider authorization session 與 Submit Passkey credential response 兩個文件。主要狀態如下：

狀態	意義	操作
awaiting_qr_scan	QR code 有效	顯示給帳號持有人，並輪詢 GET /v1/accounts/{account_id}/auth 或 POST /v1/accounts/{account_id}/auth/qr/check。
passkey_required	WhatsApp 需要 WebAuthn credential	開啟託管的 authorize_url，讓持有人完成瀏覽器提示。
passkey_pending	Credential 已提交	繼續輪詢認證狀態，不要啟動新流程。
passkey_confirmation	需要額外確認	持有人確認後呼叫 POST /v1/accounts/{account_id}/auth/passkey-confirm。
authorized	認證完成	runtime 通常會自動啟動；觀察 account.auth.succeeded 和 account.started。

步驟 1：先建立 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 }
}'

正式環境的接收端應以 raw body 驗證 X-Device-Signature。完整規則見 Webhook delivery：HMAC-SHA256 的輸入是 X-Device-Timestamp + "." + raw request body。

步驟 2：建立 WhatsApp messaging account

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；認證狀態、QR code 和 Passkey payload 則從認證端點讀取。

步驟 3：啟動 QR 認證並接續 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 credential response；你的可信任交接層再將它送到 POST /v1/accounts/{account_id}/auth/passkey-response。若狀態變成 passkey_confirmation，在持有人確認後呼叫 /auth/passkey-confirm，再輪詢 /auth 直到 authorized 或 failed。

步驟 4：確認第一筆入站事件

認證成功後，通常會先看到 account event，接著收到一般入站訊息：

{
  "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 inbound 一樣儲存與路由。若你還在比較整體架構，可參考連接 Telegram 使用者帳號到 Webhook與第一把 API key 的 Webhook 測試清單。

限制與取捨

若你需要官方商業身分、樣板訊息、官方分析或 Meta 管理的完整政策層，應選擇 WhatsApp Business Platform。若你的目標是把既有普通 WhatsApp inbox 接到簽名 Webhook，UnifyPort 的非官方接口可更快支援入站流程。

Passkey 不會取消使用者確認。它只是把確認步驟寫清楚：使用者完成 credential prompt，伺服器不保存敏感認證資料，Webhook 在帳號上線前已經就緒。

FAQ

passkey_required 是錯誤嗎？

不是。它是 WhatsApp QR 認證的正常延續狀態。請繼續目前 session 並提交瀏覽器產生的 credential response。

QR 進入 Passkey 後要建立新帳號嗎？

不要。新帳號可能造成重複 provider identity 衝突。請繼續輪詢目前 auth state。

應該保存哪些資料？

保存 account_id、auth state、Webhook event ID 與收到的訊息。不要把完整授權 URL 或 WebAuthn credential response 寫入 log。

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