Webhook Event: passkey.updated

Triggered when a WhatsApp Passkey linking request changes stage. This event is useful if your application wants to track Passkey linking progress in real time.

Payload format

Webhook requests are sent as a JSON payload with the event name, session ID, data object, and timestamp.

{
  "event": "passkey.updated",
  "sessionId": "YOUR_SESSION_API_KEY",
  "data": {
    "stage": "request",
    "requestId": "passkey-request-id",
    "token": "temporary-passkey-token",
    "expiresAt": 1783619400000
  },
  "timestamp": 1783619100000
}

Passkey stages

Stage	Meaning	Recommended action
request	A Passkey request was created. The payload includes the temporary token and request ID.	Show the token to the user and ask them to paste it into Device Link Helper, or start your own helper flow.
confirmation	WhatsApp returned the continuation data and the request is ready to be confirmed.	If you use Device Link Helper, no action is needed. If you built your own helper, call /api/passkey/confirm.
fallback_qr	The proactive Passkey flow did not finish in time and the session is switching back to QR linking.	Stop the Passkey flow and show the QR linking UI. Watch for session.status with need_scan.
no_continuation	WhatsApp acknowledged the Passkey prologue but did not continue the linking flow.	Ask the user to retry Passkey linking or use QR linking.

Stage details

The request stage can include:

• requestId — ID of the Passkey request.
• token — temporary token used by Device Link Helper or a custom helper.
• expiresAt — expiration timestamp for the temporary token.

The confirmation stage can include:

• requestId — ID of the Passkey request.
• code — internal confirmation value returned by WhatsApp. The website and helper do not show this code to the user.
• skipHandoffUx — whether WhatsApp can skip part of the handoff UX.

The fallback_qr and no_continuation stages can include:

• requestId — ID of the Passkey request.
• error — user-readable reason for the fallback or failure.