Qué datos enviar a Laiki por webhook (leads y eventos)
Tutorial completo para enviar datos por webhook a Laiki: campos de lead y evento, obligatorios, identificación del lead e idempotencia.
Publicado el
6 min de lectura
Para enviar datos por webhook a Laiki, tu herramienta hace un POST con un JSON que contiene dos entidades: el lead (la persona) y el evento (la acción que ocurrió). En el evento, tres campos son obligatorios: name, date y externalSource. En el lead, basta un identificador entre email, teléfono y externalId. Este tutorial lista todos los campos aceptados, explica cómo Laiki identifica a cada lead y muestra por qué ningún evento entra duplicado, incluso cuando la herramienta reenvía el mismo disparo.
Sirve para cualquier sistema capaz de disparar un payload (el paquete de datos) en JSON: CRM, plataforma de automatización, formulario de sitio, chatbot o un sistema propio de tu empresa.
Cómo funciona el envío, paso a paso
1. La herramienta dispara el webhook. En cada acción acordada (nuevo lead, conversión, cambio de etapa), la herramienta de origen envía un POST con los datos en JSON a la dirección del workflow.
2. Laiki recibe el payload. El workflow lee los campos del JSON y organiza qué es dato de la persona y qué es dato de la acción.
3. Lead y evento se guardan. El workflow crea el lead (o lo actualiza, si ya existe en la base) y registra el evento, listo para segmentaciones, dashboards, reportes y consultas por agente de IA, ya que Laiki es un software agéntico con datos accesibles vía MCP.
Ese es el camino completo de quien decide enviar datos por webhook a Laiki. Quien arma el workflow somos nosotros; lo que tu herramienta necesita garantizar es solo el contenido del envío, y de eso tratan las dos tablas siguientes.
Campos de la entidad Lead
La entidad Lead lleva los datos de la persona. Ningún campo aquí es obligatorio de forma aislada, pero hay una regla de identificación justo debajo de la tabla.
| Campo | Tipo | Para qué sirve |
|---|---|---|
| name | texto | Nombre del lead |
| texto | Email principal | |
| phone | texto | Teléfono principal |
| company | texto | Empresa del lead |
| jobTitle | texto | Cargo en la empresa |
| tags | texto | Etiquetas para organizar el lead (origen, producto de interés) |
| notes | texto | Observaciones libres |
| externalId | texto | ID del lead en la herramienta de origen, para cruzar las dos bases |
| createdAt | texto (fecha) | Fecha de creación del lead en la herramienta de origen |
Regla práctica: envía todo lo que tenga la herramienta de origen. Cada campo completado mejora las segmentaciones y los reportes que salen del otro lado.
Cómo identifica Laiki al lead
La identidad del lead se compone de email, teléfono y/o externalId: basta UNO de ellos en cada envío, no los tres. Por ese identificador Laiki reconoce a la persona. ¿Identificador que ya existe en la base? El evento entra en el lead que ya está allí y el registro se actualiza. ¿Identificador inédito? Se crea un lead nuevo, y eso es lo que impide registros duplicados de la misma persona.
Un envío sin ninguno de los tres no tiene a quién pertenecer, así que asegura al menos uno de ellos en el payload.
Material de apoyo · En portuguésGuía de Prompts para Marketing y Ventas70 prompts con preguntas sobre marketing, ventas y comportamiento para hacerles a tus datos.Descargar la guía
Campos de la entidad Event
La entidad Event describe la acción: el llenado del formulario, el cambio de etapa, la compra. Aquí existen tres campos obligatorios, marcados en la tabla.
| Campo | Tipo | ¿Obligatorio? | Para qué sirve |
|---|---|---|---|
| name | texto | Sí | Nombre del evento (formulario_contato, lead_qualificado) |
| date | texto (fecha/hora) | Sí | Fecha y hora en que ocurrió el evento |
| externalSource | texto | Sí | Origen del dato (el nombre de la herramienta que envía) |
| value | número | No | Valor monetario asociado, cuando lo haya |
| url | texto | No | URL de la página donde ocurrió el evento |
| domain | texto | No | Dominio del sitio |
| device | texto | No | Dispositivo del visitante (mobile, desktop) |
| source | texto | No | Canal o fuente del evento |
| identifier | texto | No | Identificador libre del evento |
| externalId | texto | No | ID del evento en la herramienta de origen |
| utmSource | texto | No | UTM de origen de la campaña |
| utmMedium | texto | No | UTM de medio de la campaña |
| utmCampaign | texto | No | UTM de nombre de la campaña |
| utmContent | texto | No | UTM de contenido del anuncio |
| utmTerm | texto | No | UTM de término o palabra clave |
| utmChannel | texto | No | Canal consolidado de la campaña |
Sin name, date y externalSource, el evento no se registra. Los seis campos de UTM merecen atención especial: son los que alimentan la atribución de canal. Siempre que la información de campaña exista en la herramienta de origen, vale la pena enviarla.
Idempotencia: por qué el mismo evento nunca entra dos veces
Los webhooks fallan en la práctica: la red oscila, la herramienta no recibe la confirmación y reenvía el mismo disparo. Si cada reenvío se convirtiera en un evento nuevo, los conteos de conversión se inflarían y el embudo pasaría a mentir.
La idempotencia es la garantía de que repetir la misma operación produce el mismo resultado que una única ejecución, un concepto de la propia especificación HTTP, documentado en el glosario de MDN Web Docs. En Laiki, cada evento lleva una clave de idempotencia generada de nuestro lado, a partir de los datos del propio envío (identificador del lead, nombre del evento, fecha). ¿Llegó una clave que ya fue guardada? El evento no entra de nuevo. No necesitas crear ni enviar esa clave: puedes reenviar sin miedo, el conteo no se duplica.
¿Y si mi herramienta tiene campos fuera de la lista?
Las tablas de arriba cubren los campos nativos. Cuando la herramienta de origen captura algo que no encaja en ellos, como la respuesta a una pregunta específica del formulario, creamos un campo personalizado en tu cuenta para recibir ese dato, en el tipo correcto (texto, número, fecha o verdadero/falso). Basta con que enumeres qué campos extra existen en tu payload y preparamos la cuenta antes del primer disparo.
Preguntas frecuentes
¿Necesito un programador para enviar datos por webhook?
En la mayoría de los casos, no. La mayor parte de los CRM, plataformas de automatización y constructores de formularios ya tienen la opción de disparar webhooks desde su propia interfaz: pegas la dirección, eliges el disparador y mapeas los campos. La programación solo entra cuando el envío parte de un sistema propio de tu empresa.
¿En qué formato deben enviarse los datos?
En JSON, mediante una solicitud POST. Los nombres de los campos pueden venir como los genera tu herramienta: el mapeo entre su payload y los campos de Laiki se hace en el workflow, de nuestro lado. Lo que importa es que el dato esté presente en el envío.
¿Qué pasa si un envío falla?
Si el disparo no llega, la mayoría de las herramientas vuelve a intentarlo automáticamente. Y ahí es donde la idempotencia trabaja a tu favor: la herramienta puede reenviar el mismo paquete las veces que necesite, porque Laiki reconoce la repetición y registra el evento una sola vez.
Arma la integración con nosotros
Si todavía no usas Laiki y quieres dejar de perder datos entre una herramienta y otra, habla con nosotros: armamos el workflow de recepción junto contigo, y quien quiera enviar datos por webhook a tu operación va a encontrar todo listo del otro lado.
