Webhooks
Los Webhooks te permiten recibir eventos del workspace en tiempo real en tu propio endpoint. Cada vez que ocurre algo (se crea una conversación, llega un mensaje, se actualiza un cliente…), Platica envía una petición HTTP a la URL que configures.
A diferencia de las Aplicaciones y API REST —donde es tu agente quien consulta hacia afuera—, los webhooks van en sentido contrario: es Platica quien avisa a tus sistemas cuando algo sucede.
Cada solicitud se firma con HMAC SHA-256 (si configuras un secret) y cuenta con reintentos automáticos si tu endpoint no responde.
Para empezar, haz clic en "Crear webhook". El asistente tiene tres pasos: Endpoint → Eventos → Listo.
Paso 1: Endpoint
Define dónde y cómo se entregarán los eventos.
| Campo | Descripción |
|---|---|
| Nombre | Cómo identificarás este webhook (por ejemplo, "CRM externo - producción"). Hasta 100 caracteres. |
| URL del endpoint | La dirección que recibirá los eventos. Debe ser una URL pública accesible (HTTPS recomendado). |
| Activo desde el inicio | Si el webhook empieza a entregar eventos de inmediato. Puedes pausarlo en cualquier momento. |
| Secret de firma (opcional) | Una cadena aleatoria que solo tú conoces. Puedes escribirla o usar "Generar". |
| Headers personalizados | Encabezados HTTP extra (hasta 10). Útil para enviar tokens propios (por ejemplo, Authorization: Bearer ...). |
Valida la autenticidad con el secret. Si lo configuras, cada solicitud llevará el header X-Webhook-Signature: sha256=<hmac> calculado sobre el cuerpo JSON. Tu endpoint puede recalcular ese HMAC con el mismo secret para confirmar que el evento viene realmente de Platica.
Antes de terminar, usa "Probar entrega" para enviar un payload de ejemplo (con su firma HMAC) y ver la respuesta de tu endpoint. Puedes elegir el tipo de payload de prueba (por ejemplo, "Ping genérico").
Paso 2: Eventos
Elige a qué eventos quieres suscribirte. Hay 18 eventos agrupados en cuatro categorías; marca solo los que necesites.
Conversaciones
Ciclo de vida de cada conversación: creación, cambios de estado, dueños, etiquetas y expiración.
| Evento | Cuándo se dispara |
|---|---|
conversation.created | Nueva conversación creada en el workspace. |
conversation.status.updated | Estado de la conversación actualizado (open, pending, finished, spam, …). |
conversation.operation.updated | Operación / pipeline asignada a la conversación. |
conversation.owners.updated | Propietarios de la conversación añadidos o removidos. |
conversation.tags.updated | Etiquetas de la conversación añadidas o removidas. |
conversation.expired | Conversación expirada (por ejemplo, la ventana de 24 h de WhatsApp). |
Mensajes
Mensajes individuales dentro de una conversación: creación, actualización y borrado.
| Evento | Cuándo se dispara |
|---|---|
message.created | Nuevo mensaje creado en una conversación. |
message.updated | Mensaje actualizado (estado, contenido editado, etc.). |
message.deleted | Mensaje eliminado. |
Clientes
Cambios sobre el perfil del cliente: datos básicos, dueños, etiquetas y campos personalizados.
| Evento | Cuándo se dispara |
|---|---|
client.created | Nuevo cliente creado. |
client.updated | Cliente actualizado (datos básicos). |
client.owners.updated | Propietarios del cliente añadidos o removidos. |
client.tags.updated | Etiquetas del cliente añadidas o removidas. |
client.customFields.updated | Cambios en campos personalizados del cliente. |
WhatsApp Flows
Interacciones con WhatsApp Flows. Tu endpoint debe responder con JSON en menos de 700 ms.
| Evento | Cuándo se dispara |
|---|---|
whatsapp.flows.init | Inicio de un WhatsApp Flow (action INIT desde Meta). |
whatsapp.flows.screen_advance | Avance de pantalla en el flow (action data_exchange). |
whatsapp.flows.back | Regreso a la pantalla anterior (action BACK). |
whatsapp.flows.exchanges | Suscripción "paraguas": recibe init, screen_advance y back en un único webhook. |
Los eventos de WhatsApp Flows requieren que tu endpoint responda con un JSON válido en menos de 700 ms. Si tu servidor tarda más, Meta cancela el flow. Úsalos solo si vas a procesar flows interactivos.
Paso 3: Listo
El webhook queda creado y Platica comenzará a entregar eventos en cuanto ocurran.
Desde aquí puedes "Volver al listado" o ir a "Ver detalles", donde encontrarás los logs de entrega de cada evento.
Administrar tus webhooks
El listado muestra todos los webhooks que has creado, con su estado (activo), si está Firmado (tiene secret configurado), la URL y a cuántos eventos está suscrito. Puedes ordenarlos por Recientes o Alfabético y buscarlos por nombre.
Detalle del webhook
Al abrir un webhook ves de un vistazo su estado (Activo), la URL, la firma (con o sin secret) y el número de eventos suscritos, además de un acceso directo a Logs.
Entregas recientes lista las últimas 5 entregas con su estado, evento, código HTTP y latencia. Usa "Probar" para enviar un evento de prueba (puedes elegir cuál) o "Ver historial completo" para abrir los logs.
Configuración
Desde la configuración puedes cambiar el nombre, la URL, agregar o quitar el secret de firma, gestionar los headers personalizados y ajustar a qué eventos está suscrito.
Logs de entrega
El historial completo de intentos de entrega de este webhook. Los registros se conservan 30 días y luego se eliminan automáticamente.
Arriba ves métricas agregadas: Total, Éxitos, Errores, Tasa de error y latencias P50 / P95. Puedes filtrar por Todos / Éxitos / Errores, filtrar por evento, buscar y Exportar el historial en JSON o CSV.
Al desplegar una entrega ves su detalle completo:
| Dato | Descripción |
|---|---|
| URL | El endpoint al que se entregó el evento. |
| Event ID | Identificador único del evento. |
| HTTP | Código de respuesta de tu endpoint (por ejemplo, 429 Too many requests). |
| Expira | Fecha en que el registro se eliminará (a los 30 días). |
| Request body | El payload JSON que Platica envió. |
| Response body | La respuesta que devolvió tu endpoint. |
Si tu endpoint no responde con un código exitoso, Platica aplica reintentos automáticos. Revisa los logs para diagnosticar entregas fallidas (códigos 4xx/5xx, timeouts, etc.).