Events & webhooks
Enable a webhook on a link to receive real-time notifications at a URL you control. When something happens
we send your endpoint a JSON POST and, for exactly the events you subscribed to,
signed with a shared secret.
Overview#
| Request | JSON POST to your payload URL. |
|---|---|
| On success | Reply with any 2xx. Retries use exponential backoff (up to 5 attempts); most 4xx responses are treated as permanent. |
| Timeout | 10 seconds per attempt. |
| Idempotency | Use the X-Webhook-Id header (also in the body as id) to deduplicate deliveries. message_id is stable for message events. |
| Ordering | Deliveries can arrive out of order. Each payload has a sequence that increases for each link; sort by it to rebuild the order. The payload timestamp is the event time. |
| Audit | Recent attempts, response codes and errors appear in the link's Webhook page, with a retry button for failures that can still be sent again. |
Webhook setup#
- Open a link in your dashboard and go to its Webhook page.
- Toggle the webhook on and enter your Payload URL — a public
httpsendpoint on your own server, e.g.https://example.com/webhooks/wacentraconnect. PlainhttpURLs are rejected. - Choose the events you want to receive and save. We generate a webhook secret for signing.
- Rotate the secret any time from the same page; the old one stops working immediately.
| Header | Value |
|---|---|
X-Webhook-Event | The event name, e.g. messages.received. |
X-Webhook-Id | Unique delivery ID; also sent as Idempotency-Key. |
X-Webhook-Timestamp | Current attempt time used in the signature; refreshed on every retry. The original event time is timestamp in the body. |
X-Webhook-Signature | sha256= + HMAC-SHA256 of the raw request body (legacy format). |
X-Webhook-Signature-V2 | sha256= + HMAC-SHA256 of event + "\n" + timestamp + "\n" + body. Recommended. |
Content-Type | application/json. |
data.kind is usually
personal, group or newsletter.
Message logging off. If a link disables message logging, webhook payloads omit
text, body and caption;
identifiers remain so you can still route events. Delivery payloads are encrypted at rest and successful
records are pruned after 7 days.
Overlapping events. Subscribing to both
messages.received and a
specific event such as messages-personal.received produces one delivery per
subscription. Deduplicate with X-Webhook-Id or message_id.
Event catalog#
Subscribe to any of the events below. messages.received and
session.status are enabled by default when you first turn a webhook on.
| Event | Fires when | data |
|---|---|---|
messages.received | Any incoming message that passes your filters. | { message_id, from, text, type, media, kind } |
messages-personal.received | An incoming one-to-one message. | same as above |
messages-group.received | An incoming group message. | same as above |
messages-newsletter.received | A message from a channel (newsletter). | same as above |
session.status | The connection status changes. | { status, phone_number, display_name, last_error } |
qrcode.updated | A new pairing QR code is generated. | { qr_code } |
message.sent | A message is sent through the API. | message summary |
message-receipt.update | Delivery and read receipts arrive. | { message_id, status } |
messages.reaction | Someone reacts to a message. | reaction payload |
messages.update | Raw: a message is updated (status, edits). | raw update |
messages.upsert | Raw: a message is added or received. | raw message |
messages.delete | Raw: a message is deleted. | raw delete |
call | An incoming or outgoing call event. | call payload |
contacts.upsert / contacts.update | A contact is added or updated. | contact payload |
chats.upsert / chats.update / chats.delete | A chat is added, changed or removed. | chat payload |
groups.upsert / groups.update | A group is added or its details change. | group payload |
group-participants.update | Group members are added, removed or promoted. | participant payload |
poll.results | Someone votes in a poll. | poll payload |
For incoming media, type is image,
video, document, audio
or sticker, and media carries
filename, mime_type,
size and the base64 file bytes in data. Other
message kinds use type values of location,
contact, poll or
reaction. Files up to 16 MB are relayed; larger files produce a
metadata-only event. Files are relayed only: they are not stored by WaCentra Connect API, and
media is omitted entirely when message logging is off.
Verifying signatures#
Recompute the HMAC over the event name, timestamp and raw request body using your webhook
secret and compare it to X-Webhook-Signature-V2. Use a timing-safe comparison.
The legacy X-Webhook-Signature (body only) remains for older receivers.
Reject stale requests. Compare X-Webhook-Timestamp with your clock
and reject anything more than five minutes old, even when the signature is valid. This stops a captured
request from being replayed. Use X-Webhook-Id to ignore duplicates.
PHP
<?php
$payload = file_get_contents('php://input');
$secret = getenv('WACENTRACONNECT_WEBHOOK_SECRET');
$eventName = $_SERVER['HTTP_X_WEBHOOK_EVENT'] ?? '';
$timestamp = $_SERVER['HTTP_X_WEBHOOK_TIMESTAMP'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $eventName."\n".$timestamp."\n".$payload, $secret);
$received = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE_V2'] ?? '';
if (! hash_equals($expected, $received)) {
http_response_code(401);
exit;
}
$event = json_decode($payload, true);
// handle $event['event'], $event['session']['uuid'], $event['data']
http_response_code(204);
Node.js
const crypto = require('crypto');
const express = require('express');
const app = express();
// Served on your own server, e.g. https://example.com/webhooks/wacentraconnect
app.post('/webhooks/wacentraconnect', express.raw({ type: 'application/json' }), (req, res) => {
const signed = `${req.get('X-Webhook-Event')}\n${req.get('X-Webhook-Timestamp')}\n${req.body}`;
const signature = 'sha256=' + crypto
.createHmac('sha256', process.env.WACENTRACONNECT_WEBHOOK_SECRET)
.update(signed)
.digest('hex');
if (signature !== req.get('X-Webhook-Signature-V2')) {
return res.sendStatus(401);
}
const payload = JSON.parse(req.body);
// handle payload.event, payload.data
res.sendStatus(204);
});
Production setup: set
WHATSAPP_WORKER_SECRET in the app and
WORKER_SECRET in the worker to the same value, and use a shared cache
(Redis or database) so worker nonces cannot be replayed across servers.
© 2026 WaCentra Connect API. All rights reserved.