Events Reference - WSAPI Docs

WSAPI emits real-time events whenever something happens on your WhatsApp instance — new messages, status changes, group updates, calls, and more.

Delivery modes

There are two ways to receive events:

Webhooks (Push)
SSE (Pull)

WSAPI sends an HTTP POST request to a public endpoint you configure. Best for server-based applications that already expose HTTP endpoints.

Configure your instance with Webhook delivery mode and specify a Webhook URL
When an event occurs, WSAPI sends a POST request with the event payload
Your server processes the event and responds with a 200 status code

See Configuring Event Delivery for setup instructions.

Event payload

All events follow this structure regardless of delivery mode:

{
  "eventId": "evt_a1b2c3d4e5f67890",
  "instanceId": "ins_ABCdefGHIjk",
  "receivedAt": "2025-05-19T00:51:44.816Z",
  "eventType": "message",
  "eventData": {
    // Event-specific data
  }
}

Field	Type	Description
`eventId`	`string`	Unique event identifier
`instanceId`	`string`	The instance that generated the event
`receivedAt`	`string`	ISO 8601 timestamp when the event was received
`eventType`	`string`	The event type (e.g., `message`, `logged_in`)
`eventData`	`object`	Event-specific payload

Event types

Event	Category	Description
`logged_in`	Session	Instance connected to WhatsApp
`logged_out`	Session	Instance disconnected (includes reason)
`login_error`	Session	Pairing error occurred
`initial_sync_finished`	Session	Initial history sync completed
`message`	Messages	New message received (text, media, reaction, contact, etc.)
`message_read`	Messages	Message read/delivery receipt
`message_delete`	Messages	Message was deleted
`message_star`	Messages	Message was starred/unstarred
`message_history_sync`	Messages	On-demand history sync messages
`chat_setting`	Chats	Chat settings changed (mute, pin, read, archive, ephemeral)
`chat_presence`	Chats	Contact is typing, recording, or paused
`chat_push_name`	Chats	Contact’s push name changed
`chat_status`	Chats	Chat about/status text updated
`chat_picture`	Chats	Chat picture changed
`contact`	Contacts	Contact information updated
`group`	Groups	Group/community settings or membership changed
`newsletter`	Newsletters	Newsletter/channel subscription or mute change
`user_presence`	Users	User online/offline status changed
`call_offer`	Calls	Incoming call received
`call_accept`	Calls	Call was accepted
`call_terminate`	Calls	Call ended

Four events are system events: logged_in, logged_out, login_error, and initial_sync_finished. System events are always delivered regardless of event filter configuration and cannot be opted out of.

Webhook delivery headers

Every webhook POST request includes the following HTTP headers:

Header	Description
`Content-Type`	Always `application/json`
`X-Instance-Id`	The ID of the instance that generated the event
`X-Webhook-Signature`	HMAC-SHA256 signature of the request body. Only present when a `signingSecret` is configured.

Verifying event signatures

When a Signing Secret is configured for your instance, WSAPI signs every event payload using HMAC-SHA256. The signature is included in the X-Webhook-Signature header with the format:

sha256=<hex-encoded HMAC-SHA256>

Always configure a signing secret to verify the authenticity of incoming events and prevent unauthorized parties from sending fake events to your endpoint.

To verify an event:

Compute the HMAC-SHA256 of the raw request body using your signing secret as the key
Hex-encode the result and prepend sha256=
Compare the computed value with the X-Webhook-Signature header using a constant-time comparison to prevent timing attacks

const crypto = require("crypto");

function verifySignature(body, secret, headerValue) {
  const expected =
    "sha256=" + crypto.createHmac("sha256", secret).update(body).digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(headerValue)
  );
}

import hmac
import hashlib

def verify_signature(body: bytes, secret: str, header_value: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, header_value)

using System.Security.Cryptography;
using System.Text;

bool VerifySignature(byte[] body, string secret, string headerValue)
{
    using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
    var hash = hmac.ComputeHash(body);
    var expected = "sha256=" + Convert.ToHexString(hash).ToLowerInvariant();
    return CryptographicOperations.FixedTimeEquals(
        Encoding.UTF8.GetBytes(expected),
        Encoding.UTF8.GetBytes(headerValue));
}

Delivery and retries

WSAPI expects a 2xx response for webhook deliveries
If no valid response is received, WSAPI retries delivery up to 2 times
After that, the event is discarded
Implement idempotent processing to handle potential duplicate deliveries

Best practices

Respond quickly — return 200 immediately and process events asynchronously
Verify signatures — always validate the X-Webhook-Signature on incoming events
Handle duplicates — design your handler to be idempotent in case of retries
Filter events — use event filtering to only receive events you need
Use HTTPS — always use an HTTPS endpoint for your webhook URL
Log events — log incoming events for debugging and audit purposes

​Delivery modes

​Event payload

​Event types

​Webhook delivery headers

​Verifying event signatures

​Delivery and retries

​Best practices

Delivery modes

Event payload

Event types

Webhook delivery headers

Verifying event signatures

Delivery and retries

Best practices