Delivery and Signatures
Platica sends every webhook as a POST with Content-Type: application/json. If you configure a secret, we also include an HMAC-SHA256 signature so you can verify the event comes from Platica.
Envelope
Conversation, message, customer, and WhatsApp Flows events arrive in this envelope:
{
"id": "9f8c...",
"event": "conversation.created",
"workspaceId": "ws_456",
"timestamp": "2026-05-06T19:00:00.000Z",
"source": "system.conversation.created",
"resourceType": "conversation",
"resourceId": "conv_123",
"changes": null,
"data": {}
}| Field | Description |
|---|---|
id | Unique event identifier |
event | Name of the event received |
workspaceId | Workspace where it happened |
timestamp | ISO-8601 date of the event |
source | Origin of the event in <origin>.<resource>.<action> format — see the source field |
resourceType | conversation, message, client, or flow_response |
resourceId | ID of the affected resource |
changes | Change diff, when applicable |
data | Normalized snapshot of the resource |
For the contents of data and the possible values of source, see Payloads .
Headers
| Header | Description |
|---|---|
Content-Type | application/json |
User-Agent | Platica's User-Agent |
X-Webhook-Event | Matches payload.event |
X-Webhook-Id | Identifier of the configured webhook |
X-Webhook-Event-Id | Matches payload.id |
X-Webhook-Resource-Type | Affected resource type |
X-Webhook-Resource-Id | ID of the affected resource |
X-Webhook-Timestamp | Matches payload.timestamp |
X-Webhook-Signature | sha256=<hex> if you configured secret |
Validate the signature
The signature is computed with HMAC-SHA256 over the raw body (rawBody) received by your endpoint:
sha256=<hmac_sha256(secret, rawBody)>Node.js example:
const crypto = require('crypto');
function verifyWebhook(secret, rawBody, signatureHeader) {
const expected = 'sha256=' + crypto
.createHmac('sha256', secret)
.update(rawBody)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(expected),
Buffer.from(signatureHeader)
);
}Use the raw request body, not the reserialized JSON object. If your framework parses the body automatically, capture the rawBody before converting it to JSON.
Responses and retries
Your endpoint must respond with a 2xx status code when it processes the event successfully. For conversation, message, and customer events, your response body is not used to continue any flow; it only confirms the webhook was received.
WhatsApp Flows uses the same X-Webhook-* headers and the same signature over rawBody. The difference is that Platica does use the JSON response to continue the flow; that logic is documented in WhatsApp Flows .