contact.created

.md

Event POST <your callback URL>

A contact was created - by its first message in or out, or by you through the API.

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 contact.created.

occurred_at string

Format date-time.

business object

external_id string business.external_id

data object

contact object data.contact

id integer data.contact.id

external_id string | null data.contact.external_id

Your own id for the person.

name string | null data.contact.name

phone string | null data.contact.phone

WhatsApp number, digits.

email string | null data.contact.email

locale string | null data.contact.locale

timezone string | null data.contact.timezone

status string data.contact.status

custom_fields object data.contact.custom_fields

The business's own fields (see List contact fields).

preferences object data.contact.preferences

What the contact wants to receive - false turns it off; missing means on.

channels object data.contact.preferences.channels

Example {"whatsapp":true}.

topics object data.contact.preferences.topics

fees, results, attendance, pta, marketing, system.

Example {"fees":true,"marketing":false}.

tags array of strings data.contact.tags

identities array of objects data.contact.identities

channel string data.contact.identities[].channel

Example whatsapp.

address string data.contact.identities[].address

profile_name string | null data.contact.identities[].profile_name

The name the person shows on that channel.

last_seen_at string | null data.contact.identities[].last_seen_at

Format date-time.

created_at string data.contact.created_at

Format date-time.

updated_at string data.contact.updated_at

Format date-time.

// 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'] === 'contact.created') { Guardian::linkPaalChatContact($event['business']['external_id'], $event['data']['contact']['id'], $event['data']['contact']['phone']); } return response()->noContent(); }

{ "id": "5c6d7e8f-9a0b-4c1d-8e2f-3a4b5c6d7e8f", "event": "contact.created", "occurred_at": "2026-10-01T09:12:01+00:00", "business": {"external_id": "presec"}, "sandbox": false, "data": { "contact": { "id": 41, "external_id": "parent-77", "name": "Ama Mensah", "phone": "233241234567", "email": null, "locale": null, "timezone": null, "status": "active", "custom_fields": {"class": "SHS 2"}, "tags": ["parent"], "identities": [ { "channel": "whatsapp", "address": "233241234567", "profile_name": "Ama Mensah", "last_seen_at": "2026-10-01T09:12:00+00:00" } ], "created_at": "2026-10-01T08:00:00+00:00", "updated_at": "2026-10-01T09:12:00+00:00" } } }