WhatsApp Passkey QR Authentication: thiết lập Webhook an toàn

Quy trình ghép nối WhatsApp bằng QR đôi khi yêu cầu xác minh danh tính bằng Passkey. Khi trạng thái là passkey_required, đừng tạo lại account và đừng mở thêm một kết nối WhatsApp khác. Hãy tiếp tục authentication session hiện tại, để chủ tài khoản hoàn tất WebAuthn credential prompt trong trình duyệt, gửi response cho UnifyPort, rồi chờ authorized và các signed Webhook events sau đó.

Điểm chính

• WhatsApp Help Center giải thích rằng passkey liên kết tài khoản với hệ thống bảo mật của thiết bị, như vân tay, khuôn mặt hoặc screen lock, để xác minh danh tính.
• Linked-device flow của WhatsApp Business hỗ trợ QR code và mã 8 ký tự theo số điện thoại; cả hai có thể yêu cầu xác nhận danh tính trên điện thoại chính.
• Trong UnifyPort, Passkey là continuation state của WhatsApp QR authentication: passkey_required → passkey_pending → tùy chọn passkey_confirmation → authorized.
• Hãy đăng ký Webhook trước khi auth để không bỏ lỡ account.auth.required, account.auth.succeeded và message.received.
• Với đội ngũ ở Việt Nam thường dùng cả WhatsApp và Zalo, receiver chung nên được chuẩn bị trước. Nếu chưa có, bắt đầu với webhook-first inbound checklist và kiểm tra chữ ký bằng HMAC replay protection guide.

WhatsApp đang yêu cầu điều gì?

Đây không phải credential mới của messaging API. Đây là bước xác minh danh tính trong quá trình truy cập tài khoản WhatsApp.

Tài liệu Passkey chính thức của WhatsApp nói rằng passkey dùng hệ thống bảo mật của thiết bị và có thể được dùng khi WhatsApp cần xác minh danh tính. Tài liệu linked-device cũng mô tả cách pair WhatsApp Business bằng QR code hoặc mã số điện thoại, bao gồm xác nhận bằng biometric authentication hoặc PIN mở khóa điện thoại. Vì vậy, khi QR flow của UnifyPort đi vào nhánh Passkey, hãy xem đó là authentication ceremony cần người dùng tham gia, không phải secret mà backend tự tạo.

Backend giữ state của UnifyPort messaging account và Webhook receiver. Chủ tài khoản hoàn tất WebAuthn prompt trên browser hoặc điện thoại đã được authorize. Không ghi đầy đủ authorize_url, auth_payload.public_key hoặc serialized credential response vào logs.

UnifyPort flow

Khi triển khai, mở Create provider authorization session và Submit Passkey credential response. Các state chính:

State	Ý nghĩa	Hành động
awaiting_qr_scan	QR code đang hoạt động	Hiển thị cho chủ tài khoản và poll GET /v1/accounts/{account_id}/auth hoặc POST /v1/accounts/{account_id}/auth/qr/check.
passkey_required	WhatsApp cần WebAuthn credential	Mở hosted authorize_url để chủ tài khoản hoàn tất browser prompt.
passkey_pending	Credential đã gửi	Tiếp tục poll auth state; không bắt đầu flow mới.
passkey_confirmation	Cần xác nhận thêm	Sau khi chủ tài khoản xác nhận, gọi POST /v1/accounts/{account_id}/auth/passkey-confirm.
authorized	Authentication hoàn tất	Runtime thường tự khởi động; theo dõi account.auth.succeeded và account.started.

1. Tạo Webhook trước

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 }
}'

Production receiver nên xác minh X-Device-Signature trên raw body trước khi parse JSON. Webhook delivery định nghĩa input HMAC-SHA256 là X-Device-Timestamp + "." + raw request body.

2. Tạo 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" }
}'

Lưu account_id trả về. Account object có runtime_status; auth state, QR code và Passkey payload được đọc từ authentication endpoints.

3. Bắt đầu QR auth và tiếp tục Passkey

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

Nếu response hoặc auth check tiếp theo trả về passkey_required, gửi authorize_url cho chủ tài khoản mở. Browser tạo WebAuthn credential response; lớp auth handoff tin cậy của bạn gửi response đó tới POST /v1/accounts/{account_id}/auth/passkey-response. Nếu state trở thành passkey_confirmation, gọi /auth/passkey-confirm sau khi chủ tài khoản xác nhận, rồi poll /auth đến authorized hoặc failed.

4. Kiểm tra inbound event đầu tiên

Sau authentication thành công, thường sẽ có account event trước, rồi đến tin nhắn inbound bình thường:

{
  "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" }
  }
}

Từ đây, nhánh Passkey đã kết thúc. Lưu, deduplicate và route event giống mọi WhatsApp inbound flow khác. Nếu bạn đang thiết kế hàng đợi chung cho WhatsApp, Zalo và LINE, hãy xem thêm Telegram user account webhook setup và first API key webhook test checklist để kiểm tra trình tự auth và receiver.

Giới hạn và lựa chọn

Chọn WhatsApp Business Platform nếu bạn cần official business identity, templates, official analytics hoặc policy surface đầy đủ của Meta. Chọn UnifyPort unofficial interface khi mục tiêu là đưa inbox WhatsApp hiện có vào signed Webhook và hợp nhất với Zalo hoặc các kênh khác trong cùng inbound queue.

Passkey không loại bỏ bước user consent. Nó làm bước đó rõ ràng trong runbook: người dùng hoàn tất credential prompt, server không log dữ liệu authentication nhạy cảm, và Webhook sẵn sàng trước khi account online.

FAQ

passkey_required có phải lỗi không?

Không. Đây là continuation state bình thường của WhatsApp QR authentication. Tiếp tục session hiện tại và gửi credential response do browser tạo.

QR chuyển sang Passkey thì có nên tạo account mới?

Không. Account mới có thể gây duplicate provider identity conflict. Hãy poll auth state hiện tại và tiếp tục nhánh Passkey.

Nên lưu dữ liệu nào?

Lưu account_id, auth state, Webhook event IDs và received messages. Không lưu authorization URL đầy đủ hoặc WebAuthn credential response trong logs.

Sources checked on 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