whatsapp.connection

.md

Event POST <your callback URL>

Something changed about the business's WhatsApp connection. event is one of connected, setup_failed, token_expiring (now degraded), recovered, paused, resumed, suspended, revoked, disconnected, released (an operator freed the disconnected account; it no longer belongs to this business), or a Meta account or messaging-limit notice (e.g. ACCOUNT_VIOLATION, UPGRADE). status is the account's state afterwards (see ConnectionStatus).

Verify every callback

Check X-PaalChat-Signature on the raw body, reject timestamps older than 5 minutes, and de-duplicate on X-PaalChat-Delivery. Answer 2xx within 10 seconds. See Webhooks and callbacks.

Headers

X-PaalChat-Event string

X-PaalChat-Delivery string

Unique per event (equals body id). De-duplicate on it.

Format uuid.

X-PaalChat-Signature string

t=<unix seconds>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>. Reject if invalid or older than 300 seconds.

Pattern ^t=\d+,v1=[a-f0-9]{64}$.

Body

id string

Equals X-PaalChat-Delivery.

Format uuid.

sandbox boolean

true for sandbox businesses (test keys) - nothing reached WhatsApp.

event any

Always whatsapp.connection.

occurred_at string

Format date-time.

business object

external_id string business.external_id

data object

waba_id string data.waba_id

event string data.event

connected, setup_failed, token_expiring, recovered, paused, resumed, suspended, revoked, disconnected, released, or a Meta account/limit event name (e.g. ACCOUNT_VIOLATION, UPGRADE).

status string data.status

connected and degraded can send. pending = created or setup failed; connecting = signup in progress; degraded = working with a warning (token expiring, low quality); maintenance = paused by PaalChat operators (sends get 409 connection_paused); suspended = Meta disabled the account; revoked = the credential stopped working or access was removed at Meta; disconnected = disconnected on purpose. pending, revoked and disconnected need a new connect link.

One of: pending, connecting, connected, degraded, maintenance, suspended, revoked, disconnected.

// routes/api.php: Route::post('/paalchat/callback', PaalChatCallbackController::class); public function __invoke(Request $request) { $header = (string) $request->header('X-PaalChat-Signature'); $raw = $request->getContent(); if (! preg_match('/^t=(\d+),v1=([a-f0-9]{64})$/', $header, $m) || abs(time() - (int) $m[1]) > 300 || ! hash_equals(hash_hmac('sha256', $m[1].'.'.$raw, config('services.paalchat.callback_secret')), $m[2])) { abort(401); } // Process each delivery once. if (! Cache::add('paalchat:'.$request->header('X-PaalChat-Delivery'), true, now()->addDays(2))) { return response()->noContent(); } $event = json_decode($raw, true); if ($event['event'] === 'whatsapp.connection') { Tenant::find($event['business']['external_id'])?->update(['whatsapp_status' => $event['data']['status']]); } return response()->noContent(); }

{ "id": "5c6d7e8f-9a0b-4c1d-8e2f-3a4b5c6d7e8f", "event": "whatsapp.connection", "occurred_at": "2026-09-30T18:40:02+00:00", "business": {"external_id": "presec"}, "sandbox": false, "data": {"waba_id": "102290129340398", "event": "connected", "status": "connected"} }