Events
Receive WhatsApp events in real time with Webhooks and WebSockets: payload structure, HMAC, retries and the full event list.
To notify your application about WhatsApp events, you can use Webhooks and WebSockets.
Webhooks
Webhooks let two applications communicate in real time: when an event occurs, Wazend sends an HTTP POST request to your URL.
Per-session webhooks
Configure per-session webhooks in the session configuration:
{
"name": "S0001",
"config": {
"webhooks": [
{
"url": "https://tu-servidor.com/webhook",
"events": ["message"],
"hmac": { "key": "tu-clave-secreta" },
"retries": {
"policy": "constant",
"delaySeconds": 2,
"attempts": 15
},
"customHeaders": [
{ "name": "X-Mi-Header", "value": "Valor" }
]
}
]
}
}Retries
Available retry policies:
constant— same delay between attempts (2, 2, 2).linear— linear backoff (2, 4, 6, 8).exponential— exponential backoff with jitter.
Headers
Every webhook includes these headers:
X-Webhook-Request-Id— unique request ID.X-Webhook-Timestamp— Unix timestamp in ms.X-Webhook-Hmac— body authentication code (if you use HMAC).X-Webhook-Hmac-Algorithm— algorithm used (sha512).
HMAC authentication
Set your secret key in config.hmac.key and verify the signature in the X-Webhook-Hmac header (algorithm sha512) against the request body.
{
"name": "S0001",
"config": {
"webhooks": [
{
"url": "https://tu-servidor.com/webhook",
"events": ["message"],
"hmac": { "key": "tu-clave-secreta" }
}
]
}
}Always verify the signature
Validate the HMAC signature to protect your endpoint against malicious requests.
Examples
You can automate flows with n8n.
WebSockets
Use WebSockets to receive messages in real time.
# Listen to all sessions and events
websocat -E wss://latam-1.wazend.net/ws
# With API key
websocat -E wss://latam-1.wazend.net/ws?x-api-key=123
# Listen to specific events
websocat -E "wss://latam-1.wazend.net/ws?session=*&events=session.status&events=message"
# Listen to one session
websocat -E "wss://latam-1.wazend.net/ws?session=S0001&events=session.status"Parameters:
session— session name or*for all.events— event list or*.x-api-key— your API key.
Payload structure
{
"id": "evt_1111111111111111111111111111",
"timestamp": 1741249702485,
"event": "message",
"session": "S0001",
"metadata": {
"user.id": "123",
"user.email": "cliente@ejemplo.com"
},
"me": {
"id": "5215551234567@c.us",
"pushName": "Mi Nombre"
},
"payload": {
"...": "event-specific data"
},
"environment": {
"tier": "CORE",
"version": "2023.10.12"
},
"engine": "NOWEB"
}Metadata
You can send custom metadata when creating or updating the session; it will be included as-is in the metadata field of every webhook event. This lets you route events to the right user without additional queries to your database.
Available events
Summary of all available events. Click on each event to go to its detail:
| Event | What it's for |
|---|---|
| session.status | Session status change (STOPPED, STARTING, SCAN_QR_CODE, WORKING, FAILED, PASSKEY). |
| engine.event | Low-level engine event for debugging (not included in events=*). |
| message | Incoming message (text, audio, files). |
| message.any | All messages, including your own. |
| message.reaction | Reaction to a message. |
| message.ack | Message delivery, read or playback confirmation. |
| message.ack.group | Confirmation from a participant in a group. |
| message.waiting | Waiting message ("Waiting for this message..."). |
| message.edited | Edited message. |
| message.revoked | Deleted (revoked) message. |
| chat.archive | Chat archived or unarchived. |
| group.v2.join | You join or are added to a group. |
| group.v2.leave | You leave or are removed from a group. |
| group.v2.participants | Someone joins, leaves, is promoted or demoted. |
| group.v2.update | The group information is updated. |
| presence.update | Presence update (online, offline, typing, recording). |
| poll.vote | New poll votes. |
| poll.vote.failed | Undecryptable poll vote. |
| event.response | Response to an event message (GOING, NOT_GOING, MAYBE). |
| event.response.failed | Undecryptable event response. |
| label.upsert | Label created or updated. |
| label.deleted | Label deleted. |
| label.chat.added | Label added to a chat. |
| label.chat.deleted | Label removed from a chat. |
| call.received | Incoming call. |
| call.accepted | Call accepted (on another device). |
| call.rejected | Call rejected or ended. |
session.status
Fires when the session status changes:
STOPPEDthe session is stopped.STARTINGthe session is starting.SCAN_QR_CODEscanning the QR or logging in by phone is required. It's emitted every time the QR changes; when you receive it, get the updated QR.PASSKEY_REQUIREDWhatsApp asks for a passkey (WebAuthn);datacontains the challenge to sign.PASSKEY_CONFIRMATION_REQUIREDthe user must verify a code;datacontains the code.WORKINGthe session works and is ready.FAILEDthe session failed; try to restart, and if not, log out and start it again.
{
"event": "session.status",
"session": "S0001",
"payload": {
"status": "WORKING",
"statuses": [
{ "status": "STOPPED", "timestamp": 1700000001000 },
{ "status": "STARTING", "timestamp": 1700000002000 },
{ "status": "WORKING", "timestamp": 1700000003000 }
],
"data": null
}
}status is the current status; statuses the last 3 statuses; data carries extra status info.
Example with PASSKEY_REQUIRED:
{
"event": "session.status",
"session": "S0001",
"payload": {
"status": "PASSKEY_REQUIRED",
"statuses": [],
"data": {
"challenge": "9WVUYm9AsQ...",
"timeout": 60000,
"rpId": "web.whatsapp.com",
"allowCredentials": [
{ "id": "AX8bTgH2...", "type": "public-key", "transports": ["internal", "hybrid"] }
],
"userVerification": "required"
}
}
}Example with PASSKEY_CONFIRMATION_REQUIRED:
{
"event": "session.status",
"session": "S0001",
"payload": {
"status": "PASSKEY_CONFIRMATION_REQUIRED",
"statuses": [],
"data": { "code": "1234" }
}
}Example with Reachout Timelock (restriction on sending to new contacts, cause of error 463):
{
"event": "session.status",
"session": "S0001",
"payload": {
"status": "WORKING",
"statuses": [],
"data": {
"reachoutTimelock": {
"enforcementType": "RESTRICT_ALL_COMPANIONS",
"isActive": true,
"timeEnforcementEnds": 1784477333
}
}
}
}Reachout Timelock
DO NOT restart, log out or re-pair: the restriction is lifted automatically. Pause sending to new contacts until timeEnforcementEnds. Read more in How to avoid a ban.
Example with Message Capping (per-cycle quota of new contacts, cause of error 475):
{
"event": "session.status",
"session": "S0001",
"payload": {
"status": "WORKING",
"statuses": [],
"data": {
"messageCapping": {
"cappingStatus": "FIRST_WARNING",
"totalQuota": 1000,
"usedQuota": 640,
"cycleStart": 1782874800,
"cycleEnd": 1785553199,
"mvStatus": "NOT_ELIGIBLE",
"oteStatus": "NOT_ELIGIBLE"
}
}
}
}Message Capping
DO NOT restart, log out or re-pair: the quota doesn't reset. With cappingStatus CAPPED, pause sending to new contacts until cycleEnd. Read more in How to avoid a ban.
message
Incoming message (text/audio/files).
{
"event": "message",
"session": "S0001",
"payload": {
"id": "true_5215551234567@c.us_AAAAAAAAAAAAAAAA",
"timestamp": 1667561485,
"from": "5215551234567@c.us",
"fromMe": true,
"source": "app",
"to": "5215551234567@c.us",
"body": "Hello!",
"hasMedia": false,
"ack": 1
}
}hasMedia— indicates whether the message has media.media.url— URL to download the media.source—apporapi(when you send via API)._data— internal engine data.
message.any
Fires on all messages, including your own. Same payload as message.
{
"event": "message.any",
"session": "S0001",
"payload": {
"id": "true_5215551234567@c.us_AAAAAAAAAAAAAAAA",
"timestamp": 1667561485,
"from": "5215551234567@c.us",
"fromMe": true,
"source": "api",
"to": "5215551234567@c.us",
"body": "Hello!",
"hasMedia": false,
"ack": 1
}
}message.reaction
Reaction to a message. reaction.text is the emoji (empty if removed) and reaction.messageId the ID of the reacted message.
{
"event": "message.reaction",
"session": "S0001",
"payload": {
"id": "false_5215551234567@c.us_11111111111111111111111111111111",
"from": "5215551234567@c.us",
"fromMe": false,
"reaction": {
"text": "🙏",
"messageId": "true_5215551234567@c.us_11111111111111111111111111111111"
}
}
}message.ack
Message delivery/read confirmation:
ERROR, ack: -1— an error occurred.PENDING, ack: 0— pending message.SERVER, ack: 1— sent to the server.DEVICE, ack: 2— sent to the device.READ, ack: 3— read.PLAYED, ack: 4— played.
{
"event": "message.ack",
"session": "S0001",
"payload": {
"id": "true_5215551234567@c.us_4CC5EDD64BC22EBA6D639F2AF571346C",
"from": "5215551234567@c.us",
"fromMe": true,
"ack": 3,
"ackName": "READ"
}
}message.ack.group
Confirmation from a participant in a group (includes the participant field).
{
"event": "message.ack",
"session": "S0001",
"payload": {
"id": "true_5215551234567@g.us_4CC5EDD64BC22EBA6D639F2AF571346C_9999@lid",
"from": "5215551234567@g.us",
"participant": "9999@lid",
"fromMe": true,
"ack": 3,
"ackName": "READ"
}
}message.waiting
Occurs when "Waiting for this message. This may take a while" appears on the phone.
{
"event": "message.waiting",
"session": "S0001",
"payload": {
"id": "true_5215551234567@c.us_AAAAAAAAAAAAAAAA",
"timestamp": 1667561485,
"from": "5215551234567@c.us",
"fromMe": true,
"to": "5215551234567@c.us",
"_data": {}
}
}message.edited
Edited message. editedMessageId is the ID of the edited message and body the new text. The event id has the format false_chatId_messageId[_participant].
{
"event": "message.edited",
"session": "S0001",
"payload": {
"id": "false_5215551234567@c.us_AAAAAAAAAAAAAAAA[_5215551234567@c.us]",
"editedMessageId": "AAAAAAAAAAAAAAAA",
"body": "Nuevo texto",
"_data": {}
}
}message.revoked
Deleted (revoked) message. revokedMessageId is the ID of the deleted message and after.id the revocation event ID (format false_chatId_messageId[_participant]).
{
"event": "message.revoked",
"session": "S0001",
"payload": {
"after": {
"id": "false_5215551234567@c.us_AAAAAAAAAAAAAAAA",
"_data": {}
},
"revokedMessageId": "AAAAAAAAAAAAAAAA",
"before": null
}
}chat.archive
Chat archived or unarchived.
{
"event": "chat.archive",
"session": "S0001",
"payload": {
"id": "5215551234567@c.us",
"timestamp": 1667561485,
"archived": true
}
}group.v2.join
You join or are added to a group.
{
"event": "group.v2.join",
"session": "S0001",
"payload": {
"group": {
"id": "5215551234567@g.us",
"subject": "Grupo de trabajo",
"description": "Group description",
"invite": "https://chat.whatsapp.com/invitecode",
"membersCanAddNewMember": true,
"membersCanSendMessages": true,
"newMembersApprovalRequired": true,
"participants": [
{ "id": "5219999999999@c.us", "role": "participant" }
]
},
"timestamp": 789456123
}
}group.v2.leave
You leave or are removed from a group.
{
"event": "group.v2.leave",
"session": "S0001",
"payload": {
"group": { "id": "5215551234567@g.us" },
"timestamp": 789456123
}
}group.v2.participants
Someone joins, leaves, is promoted or demoted. type can be join, leave, promote or demote.
{
"event": "group.v2.participants",
"session": "S0001",
"payload": {
"type": "join",
"timestamp": 1666943582,
"group": { "id": "5215551234567@g.us" },
"participants": [
{ "id": "5219999999999@c.us", "role": "participant" }
],
"_data": {}
}
}Possible roles: left, participant, admin and superadmin.
group.v2.update
The group information is updated.
{
"event": "group.v2.update",
"session": "S0001",
"payload": {
"group": { "id": "5215551234567@g.us", "subject": "New group name" },
"timestamp": 789456123,
"_data": {}
}
}presence.update
Presence update. lastKnownPresence can be online, offline, typing, recording or paused. The payload.id field indicates the chat (direct or group) and participant the specific participant (in direct chats there is only one).
{
"event": "presence.update",
"session": "S0001",
"payload": {
"id": "5215551234567@c.us",
"presences": [
{
"participant": "5215551234567@c.us",
"lastKnownPresence": "typing",
"lastSeen": null
}
]
}
}poll.vote
You receive new poll votes. Identify your own with poll.fromMe.
{
"event": "poll.vote",
"session": "S0001",
"payload": {
"vote": {
"id": "false_5215551234567@c.us_83ACBE602A05C79B234B54415E95EE8A",
"to": "me",
"from": "5215551234567@c.us",
"fromMe": false,
"selectedOptions": ["Great!"],
"timestamp": 1692861427
},
"poll": {
"id": "true_5215551234567@c.us_BAE5F2EF5C69001E",
"to": "5215551234567@c.us",
"from": "me",
"fromMe": true
}
}
}poll.vote.failed
Same as poll.vote but with an empty selectedOptions (the vote couldn't be decrypted).
{
"event": "poll.vote.failed",
"session": "S0001",
"payload": {
"vote": {
"id": "false_5215551234567@c.us_2E8C4CDA89EDE3BC0BC7F605364B8451",
"to": "me",
"from": "5215551234567@c.us",
"fromMe": false,
"selectedOptions": [],
"timestamp": 1692956972
},
"poll": {
"id": "true_5215551234567@c.us_BAE595F4E0A2042C",
"to": "5215551234567@c.us",
"from": "me",
"fromMe": true
}
}
}event.response
Response to an event message. eventResponse.response can be GOING, NOT_GOING or MAYBE. Read more in Event messages.
{
"id": "evt_00000000000000000000001",
"session": "S0001",
"event": "event.response",
"payload": {
"id": "false_5215551234567@c.us_58BBBBBBBBBBBBBBBBBBBBBBBB",
"timestamp": 1747707858,
"from": "5215551234567@c.us",
"participant": null,
"fromMe": false,
"eventCreationKey": {
"id": "false_5215551234567@c.us_3EBAAAAAAAAAAAAAAAAAAAAAAAAAA",
"to": "me",
"from": "5215551234567@c.us",
"fromMe": false
},
"eventResponse": {
"response": "GOING",
"timestampMs": 1747707858429,
"extraGuestCount": 0
},
"source": "app",
"ack": null,
"ackName": "UNKNOWN",
"replyTo": null,
"_data": {}
}
}eventCreationKey— information of the original event message (id,to,from,fromMe).eventResponse.response—GOING,NOT_GOINGorMAYBE.eventResponse.timestampMs— Unix timestamp in ms of the response.eventResponse.extraGuestCount— additional guests (0 or 1).replyTo— info of the message being replied to (nullif it's not a reply).
event.response.failed
The response couldn't be decrypted (with eventResponse: null). Resend the event message to get a new response. Read more in Event messages.
{
"id": "evt_00000000000000000000001",
"session": "S0001",
"event": "event.response.failed",
"payload": {
"id": "false_5215551234567@c.us_58BBBBBBBBBBBBBBBBBBBBBBBB",
"timestamp": 1747707858,
"from": "5215551234567@c.us",
"participant": null,
"fromMe": false,
"eventCreationKey": {
"id": "false_5215551234567@c.us_3EBAAAAAAAAAAAAAAAAAAAAAAAAAA",
"to": "me",
"from": "5215551234567@c.us",
"fromMe": false
},
"eventResponse": null,
"source": "app",
"ack": null,
"ackName": "UNKNOWN",
"replyTo": null,
"_data": {}
}
}label.upsert
Label created or updated.
{
"event": "label.upsert",
"session": "S0001",
"payload": {
"id": "10",
"name": "Cliente VIP",
"color": 14,
"colorHex": "#00a0f2"
}
}label.deleted
Label deleted.
{
"event": "label.deleted",
"session": "S0001",
"payload": {
"id": "10",
"name": "",
"color": 14,
"colorHex": "#00a0f2"
}
}label.chat.added
Label added to a chat (labelId + chatId). Right after scanning the QR, label can be null.
{
"event": "label.chat.added",
"session": "S0001",
"payload": {
"labelId": "6",
"chatId": "5215551234567@c.us",
"label": null
}
}label.chat.deleted
Label removed from a chat (labelId + chatId).
{
"event": "label.chat.deleted",
"session": "S0001",
"payload": {
"labelId": "6",
"chatId": "5215551234567@c.us",
"label": null
}
}call.received
Incoming call.
{
"event": "call.received",
"session": "S0001",
"payload": {
"id": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
"from": "5215551234567@c.us",
"timestamp": 1721374000,
"isVideo": false,
"isGroup": false
}
}call.accepted
Call accepted (on another device).
{
"event": "call.accepted",
"session": "S0001",
"payload": {
"id": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
"from": "5215551234567@c.us",
"timestamp": 1721374000,
"isVideo": false,
"isGroup": false,
"_data": {}
}
}call.rejected
Call rejected or ended.
{
"event": "call.rejected",
"session": "S0001",
"payload": {
"id": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
"from": "5215551234567@c.us",
"timestamp": 1721374000,
"isVideo": false,
"isGroup": false,
"_data": {}
}
}In the WEBJS engine, call.rejected only fires when you reject the call through the API.
engine.event
Low-level engine event, for debugging and diagnostics. It's not included when subscribing with events=*; you must specify it explicitly.
{
"event": "engine.event",
"session": "S0001",
"engine": "NOWEB",
"payload": {
"event": "messages.upsert",
"data": {}
}
}