Events

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#

RequestJSON POST to your payload URL.
On successReply with any 2xx. Retries use exponential backoff (up to 5 attempts); most 4xx responses are treated as permanent.
Timeout10 seconds per attempt.
IdempotencyUse the X-Webhook-Id header (also in the body as id) to deduplicate deliveries. message_id is stable for message events.
OrderingDeliveries 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.
AuditRecent 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#

  1. Open a link in your dashboard and go to its Webhook page.
  2. Toggle the webhook on and enter your Payload URL — a public https endpoint on your own server, e.g. https://example.com/webhooks/wacentraconnect. Plain http URLs are rejected.
  3. Choose the events you want to receive and save. We generate a webhook secret for signing.
  4. Rotate the secret any time from the same page; the old one stops working immediately.
HeaderValue
X-Webhook-EventThe event name, e.g. messages.received.
X-Webhook-IdUnique delivery ID; also sent as Idempotency-Key.
X-Webhook-TimestampCurrent attempt time used in the signature; refreshed on every retry. The original event time is timestamp in the body.
X-Webhook-Signaturesha256= + HMAC-SHA256 of the raw request body (legacy format).
X-Webhook-Signature-V2sha256= + HMAC-SHA256 of event + "\n" + timestamp + "\n" + body. Recommended.
Content-Typeapplication/json.
Filters. A link can ignore groups, broadcasts or channel updates. Ignored messages and their raw metadata events never trigger webhooks. 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.

EventFires whendata
messages.receivedAny incoming message that passes your filters.{ message_id, from, text, type, media, kind }
messages-personal.receivedAn incoming one-to-one message.same as above
messages-group.receivedAn incoming group message.same as above
messages-newsletter.receivedA message from a channel (newsletter).same as above
session.statusThe connection status changes.{ status, phone_number, display_name, last_error }
qrcode.updatedA new pairing QR code is generated.{ qr_code }
message.sentA message is sent through the API.message summary
message-receipt.updateDelivery and read receipts arrive.{ message_id, status }
messages.reactionSomeone reacts to a message.reaction payload
messages.updateRaw: a message is updated (status, edits).raw update
messages.upsertRaw: a message is added or received.raw message
messages.deleteRaw: a message is deleted.raw delete
callAn incoming or outgoing call event.call payload
contacts.upsert / contacts.updateA contact is added or updated.contact payload
chats.upsert / chats.update / chats.deleteA chat is added, changed or removed.chat payload
groups.upsert / groups.updateA group is added or its details change.group payload
group-participants.updateGroup members are added, removed or promoted.participant payload
poll.resultsSomeone 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);
});
Receiving incoming messages in your own app? See the Laravel example for a ready-made webhook route.

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.