Skip to main content
These events track the connection lifecycle of a WhatsApp session: QR code generation, the pairing code, and status changes (connected, disconnected, logged out). All of them follow the common envelope — the event-specific content lives in data.

session.created

Fires when an Official API connection finishes being provisioned through the hosted connect — the SDK connect.start() flow, used by those who resell the Official API to their own customers. It is sent to that connection’s webhookUrl every time, in parallel with the result that connect.start() returns in the browser. It is the only notification that arrives on mobile: there the popup opens as a tab and the postMessage back to your page does not happen, so start() may reject even though the connection was created. Use connect.start({ metadata }) to carry your own customer identifier and find it again here in data.metadata.
string
required
Connection ID — this is the sessionId in the sending routes.
string
required
The customer’s WhatsApp Business Account at Meta.
string
required
ID of the phone number in the Cloud API.
string
required
Meta access token for that connection, already decrypted. It is a secret: it can send messages and manage the WABA.
string
required
permanent, long_lived, short_lived, or unknown.
string
Expiration in ISO-8601, or null when the token does not expire.
object
required
The free-form JSON you passed in connect.start({ metadata }). {} when it was not sent.
Because the payload carries the access token, the event is only delivered to the webhookUrl of the connection itself and only over HTTPS — an http:// endpoint is rejected, and the attempt is recorded in the log. In the webhook logs the token shows up as [REDACTED]; it only exists in the body delivered to your endpoint.

connection.qrcode

Fires when a new QR code is generated to authenticate the session. It includes the QR text and the image already rendered in base64 (PNG), ready to display.
string
required
Text content of the QR code to be scanned by WhatsApp.
string
QR code image as a data URL (base64 PNG). May be null if image generation fails — in that case, use the qr field to render it.
QR codes identical to the last one generated for the session are deduplicated and do not trigger a new webhook.

connection.paircode

Fires when a pairing code is generated (connecting by phone number, without scanning a QR).
string
required
Pairing code to be entered on the device.
string
required
Phone number the code was generated for.

connection.status

Fires on every status change of the connection. The data.status field identifies the state. The other fields vary depending on the state.
string
required
Connection state. Possible values: connected, disconnected, logged_out, and qrcode_timeout.
string
JID of the connected account. Present when the status is connected.
string
Phone number of the connected account.
string
Display name of the connected account.
string
URL of the account’s profile picture, when available.
boolean
true when the session has just connected.
string
Disconnection reason. Present in the disconnected and logged_out statuses.

logged_out (dispatched as connection.status)

When the session is logged out (e.g. the device was removed by the user), the event is delivered as connection.status with data.status: "logged_out".
There is no separate logged_out webhook event: logout is always delivered as connection.status with data.status: "logged_out". To detect that the session needs to be reconnected, check data.status === "logged_out" (and also "disconnected").

qrcode_timeout (dispatched as connection.status)

When a session spends 45 minutes generating QR codes without anyone scanning them, and without any QR request during that period, D-API hibernates the session: the process that generates the QR codes is shut down, the connection.qrcode events stop arriving, and you receive a single connection.status with data.status: "qrcode_timeout".
From then on, the session shows up as disconnected in GET /api/v1/sessions/{sessionId}, with disconnectReason: "qrcode_timeout". Nothing is deleted: the session, its settings, and the webhook stay the same. To start generating QR codes again, just request a QR as you already do:
  • GET /api/v1/sessions/{sessionId}/qr;
  • POST /api/v1/sessions/{sessionId}/connect or POST /api/v1/sessions/{sessionId}/restart;
  • GET /api/v1/sessions/{sessionId}/pair-code;
  • open the session’s public QR link.
The first request wakes the session up and responds as before, with the previous QR marked as expired (expired: true). The new QR arrives within a few seconds, through the QR route itself (query it again) or through the connection.qrcode event. Each QR request also resets the 45-minute countdown, so a screen that polls the QR while the user has it open is never hibernated.
qrcode_timeout is not an error and requires no action if nobody is trying to connect that number. If you show the QR to your user only from the connection.qrcode webhook, handle qrcode_timeout by calling GET /api/v1/sessions/{sessionId}/qr when they return to the connection screen.