Integraciones

Las integraciones envían automáticamente los clientes de tu organización a otra herramienta. Cada cliente creado, o cuyo email o nombre cambia, se envía. Los clientes sin email nunca se envían.

Todo está en Reglas y ajustes en la barra lateral, y luego la pestaña Integraciones, visible para el propietario y los administradores de la organización. Las integraciones están incluidas en el plan Pro: con otro plan, la pantalla muestra Requiere el plan Pro y no se envía nada.

AgentsMail

Añade cada cliente a una lista de AgentsMail.

1. Conectar → pega tu clave API de AgentsMail → Verificar la clave.
2. Elige la lista de destino.
3. Guarda.

La clave se verifica con AgentsMail y luego se guarda cifrada. No se vuelve a mostrar nunca; deja el campo vacío al editar para conservar la clave guardada. Un contacto se crea o se actualiza con el email, el nombre y los apellidos.

Eliminar la integración detiene el envío; los contactos que ya están en la lista se quedan en ella.

Webhook

Envía cada evento como un POST JSON a una URL tuya.

• La URL debe ser https:// y accesible públicamente — las redes privadas y localhost se rechazan. Las redirecciones no se siguen.
• Responde con cualquier 2xx en menos de 10 segundos. Cualquier otra respuesta cuenta como un fallo y la entrega se reintenta varias veces.
• El secreto de firma se muestra una sola vez, al crear el webhook. Consérvalo.

Eventos

{
  "event": "customer.created",
  "id": "5d27589a-…",
  "email": "elena@marchetti.studio",
  "firstName": "Elena",
  "lastName": "Marchetti",
  "fullName": "Elena Marchetti",
  "organizationId": "8b1f…",
  "occurredAt": "2026-10-01T06:12:44.000Z"
}

La primera palabra del nombre pasa a ser firstName, el resto lastName. Una sincronización masiva añade "source": "bulk_sync".

Verificar la firma

Dos cabeceras acompañan cada llamada:

• X-VillaSlot-Event — el nombre del evento
• X-VillaSlot-Signature — t=<unix timestamp>,v1=<signature>

v1 es el HMAC-SHA256 en hexadecimal de <t>.<raw body>, con tu secreto de firma como clave. Calcúlalo sobre el cuerpo en bruto, antes de analizar el JSON, y rechaza las marcas de tiempo antiguas:

import {createHmac, timingSafeEqual} from 'node:crypto'

export const isValidVillaSlotSignature = (
  rawBody: string,
  header: string,
  secret: string
) => {
  const parts = Object.fromEntries(
    header.split(',').map((part) => part.split('=') as [string, string])
  )
  const timestamp = Number(parts.t)
  if (!timestamp || Math.abs(Date.now() / 1000 - timestamp) > 300) {
    return false
  }
  const expected = createHmac('sha256', secret)
    .update(`${parts.t}.${rawBody}`)
    .digest('hex')

  return (
    expected.length === parts.v1?.length &&
    timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1))
  )
}

Sincronización masiva

Los clientes nuevos y modificados se envían de forma continua. Para enviar los clientes que ya tenías, usa Sincronizar todos los clientes en una integración. Se ejecuta en segundo plano; la tarjeta indica cuántos se han enviado, omitido (sin email) y fallado.

Estado

Cada tarjeta de integración indica si está activa, desactivada o fallando, el último envío correcto y el último error. Una integración desactivada no envía nada hasta que se vuelve a activar.