Skip to main content
Webhooks notify your system in real time about what happens in each unofficial WhatsApp session: received and sent messages, status changes, connection events, chat/contact updates and group activity.

Per-session configuration

Each session has its own webhook configuration, with two delivery modes:
All enabled events of the session are sent to the same URL. Useful when a single endpoint handles all the processing.
Each event has its own webhookUrl, so you can route different events to different endpoints.
Regardless of the mode, each event has:
boolean
Turns delivery of the event on or off. Disabled events are not sent.
string
Destination URL of the event (in per_event mode) or inherited from the single configuration (in single mode).

Common envelope

Every webhook arrives with the same envelope. The event-specific content is in data.
string
required
Event name (e.g. messages.received).
string
required
ID of the session that originated the event.
object
required
Event-specific content. See each event’s page.
string
required
Date and time of delivery in ISO 8601 (UTC).
string
Identifier for end-to-end tracing. Useful in logs and support requests.

Headers

This product does not send an HMAC signature with webhooks. To restrict the origin, we recommend using a secret URL (with a token in the path) and/or validating the User-Agent and the expected sessionId.

Delivery and reliability

On failure, delivery is retried up to 7 times with exponential backoff: approximately 5s, 10s, 20s, 40s, 80s and 160s between attempts.
HTTP 404 or 410 responses are treated as a permanent failure: delivery is no longer retried for that URL.
Each attempt has a 30-second timeout. Slow endpoints may be considered a failure and be retried.
There is a per-URL circuit breaker: URLs that fail repeatedly are temporarily paused to avoid overload.
Events go through Redis-based deduplication (5-minute TTL), reducing duplicate deliveries of the same event within a short interval.
Respond quickly with a 2xx status. Do heavy processing asynchronously (queue/worker) and acknowledge receipt as soon as possible to avoid timeouts (30s) and unnecessary retries.

Available events