Entrega y Firmas

Platica envía cada webhook como un POST con Content-Type: application/json. Si configuras un secret, también incluimos una firma HMAC-SHA256 para que puedas validar que el evento viene de Platica.

Envelope

Los eventos de conversaciones, mensajes y clientes llegan con este 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": {}
}

Campo	Descripción
`id`	Identificador único del evento
`event`	Nombre del evento recibido
`workspaceId`	Workspace donde ocurrió
`timestamp`	Fecha ISO-8601 del evento
`source`	Origen del evento, en formato `<origin>.<resource>.<action>` — ver Campo `source`
`resourceType`	`conversation`, `message` o `client`
`resourceId`	ID del recurso afectado
`changes`	Diff del cambio, cuando aplica
`data`	Snapshot normalizado del recurso

Para ver el contenido de data y los valores posibles de source, consulta Payloads .

Headers

Header	Descripción
`Content-Type`	`application/json`
`User-Agent`	User-Agent de Platica
`X-Webhook-Event`	Igual a `payload.event`
`X-Webhook-Id`	Identificador del webhook configurado
`X-Webhook-Event-Id`	Igual a `payload.id`
`X-Webhook-Resource-Type`	Tipo de recurso afectado
`X-Webhook-Resource-Id`	ID del recurso afectado
`X-Webhook-Timestamp`	Igual a `payload.timestamp`
`X-Webhook-Signature`	`sha256=<hex>` si configuraste `secret`

Validar firma

La firma se calcula con HMAC-SHA256 sobre el cuerpo crudo (rawBody) que recibió tu endpoint:

sha256=<hmac_sha256(secret, rawBody)>

Ejemplo en Node.js:

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)
  );
}

Advertencia

Usa el cuerpo crudo de la petición, no el objeto JSON reserializado. Si tu framework parsea el body automáticamente, guarda el rawBody antes de convertirlo a JSON.

Respuestas y reintentos

Tu endpoint debe responder con un código 2xx cuando procese el evento correctamente. Para eventos de conversaciones, mensajes y clientes, el cuerpo de tu respuesta no se usa para continuar ningún flujo; sólo confirma que recibiste el webhook.

Nota

WhatsApp Flows usa otros headers (X-Platica-*) y otra firma que incluye timestamp. Esa lógica está documentada en WhatsApp Flows .

Anterior Listar Eventos Siguiente Payloads