WhatsApp Passkey QR Authentication: безопасная настройка Webhook

QR-привязка WhatsApp иногда переходит к проверке личности через Passkey. Если состояние стало passkey_required, не создавайте новый аккаунт и не запускайте второе подключение WhatsApp. Продолжайте ту же authentication session: владелец аккаунта завершает WebAuthn credential prompt в браузере, ваш доверенный слой передает response в UnifyPort, затем вы ждете authorized и подписанные Webhook-события.

Коротко

• В официальном WhatsApp Help Center сказано, что passkey связывает аккаунт с системой безопасности устройства: отпечатком пальца, распознаванием лица или экранной блокировкой.
• Linked-device flow в WhatsApp Business поддерживает QR-код и 8-символьный код по номеру телефона; оба сценария могут потребовать подтверждения личности на основном телефоне.
• В UnifyPort Passkey — это продолжение WhatsApp QR authentication: passkey_required → passkey_pending → опционально passkey_confirmation → authorized.
• Webhook нужно зарегистрировать до authentication, чтобы не пропустить account.auth.required, account.auth.succeeded и последующие message.received.
• Если receiver еще не готов, начните с webhook-first inbound checklist, а для проверки подписей держите рядом HMAC replay protection guide.

Что именно требует WhatsApp

Это не новый credential для messaging API. Это шаг подтверждения личности внутри доступа к WhatsApp-аккаунту.

Официальная статья WhatsApp о Passkey объясняет, что passkey использует систему безопасности устройства и может применяться, когда WhatsApp нужно подтвердить личность. Документация по linked devices также описывает привязку WhatsApp Business через QR-код или телефонный код, включая подтверждение через biometric authentication или PIN разблокировки телефона. Поэтому, когда QR flow в UnifyPort возвращает Passkey-состояние, относитесь к нему как к user-facing authentication ceremony, а не как к secret, который сервер может создать самостоятельно.

Backend хранит состояние UnifyPort messaging account и Webhook receiver. Владелец аккаунта завершает WebAuthn prompt в браузере или на авторизованном телефоне. Не записывайте в логи полный authorize_url, auth_payload.public_key или serialized credential response.

Поток в UnifyPort

Во время реализации откройте Create provider authorization session и Submit Passkey credential response. Основные состояния:

State	Значение	Действие
awaiting_qr_scan	QR-код активен	Покажите его владельцу аккаунта и опрашивайте GET /v1/accounts/{account_id}/auth или POST /v1/accounts/{account_id}/auth/qr/check.
passkey_required	WhatsApp требует WebAuthn credential	Откройте hosted authorize_url; владелец завершает browser credential prompt.
passkey_pending	Credential отправлен	Продолжайте polling auth state; не запускайте новый flow.
passkey_confirmation	Нужное дополнительное подтверждение	После подтверждения владельца вызовите POST /v1/accounts/{account_id}/auth/passkey-confirm.
authorized	Authentication завершена	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 }
}'

Production receiver должен проверять X-Device-Signature по raw body до JSON parse. В 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. Account object показывает runtime_status; auth state, QR-код и Passkey payload читаются через authentication endpoints.

3. Запустите QR authentication и продолжите Passkey

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

Если response или последующая проверка возвращает passkey_required, передайте authorize_url владельцу аккаунта. Браузер создаст WebAuthn credential response. Отправляйте его в POST /v1/accounts/{account_id}/auth/passkey-response только из доверенного auth handoff layer. Если состояние стало passkey_confirmation, после подтверждения вызовите /auth/passkey-confirm, затем опрашивайте /auth до authorized или failed.

4. Проверьте первое входящее событие

После успешной authentication обычно сначала приходит 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 branch завершен. Сохраняйте, дедуплицируйте и маршрутизируйте события как обычный WhatsApp inbound flow. Для сравнения общей настройки полезны Telegram user account webhook setup и first API key webhook test checklist.

Ограничения и выбор подхода

WhatsApp Business Platform подходит, если вам нужны official business identity, templates, official analytics или полный policy surface Meta. UnifyPort unofficial interface подходит, если главная задача — подключить существующий обычный WhatsApp inbox к подписанному Webhook без ожидания официальной бизнес-настройки.

Passkey не отменяет user consent. Он делает этот шаг явным в runbook: пользователь завершает credential prompt, сервер не логирует чувствительные данные ceremony, а Webhook готов до выхода аккаунта online.

FAQ

passkey_required — это ошибка?

Нет. Это нормальное continuation state для WhatsApp QR authentication. Продолжайте текущую session и отправьте credential response, созданный браузером.

Нужно ли создавать новый account после перехода QR к Passkey?

Нет. Новый account может вызвать duplicate provider identity conflict. Продолжайте polling текущего auth state.

Что нужно хранить?

Храните account_id, auth state, Webhook event IDs и received messages. Не храните полный authorization URL или WebAuthn credential response в логах.

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