Webhooks

Los webhooks permiten que Zelta Chat se comunique con sistemas externos en tiempo real. Cuando ocurre un evento relevante (nueva conversación, mensaje recibido, contacto creado, etc.), Zelta Chat envía una solicitud HTTP con los datos del evento a la URL que hayas configurado.

Tipos de webhooks

Tipo	Dirección	Descripción
Saliente (Outbound)	Zelta Chat hacia tu sistema	Notifica eventos que ocurren en Zelta Chat
Entrante (Inbound)	Tu sistema hacia Zelta Chat	Permite que sistemas externos envíen datos a Zelta Chat

Webhooks salientes

Crear un webhook saliente

1. Ve a Ajustes > Integraciones > Webhooks.
2. Haz clic en + Agregar webhook.
3. Ingresa la URL de destino donde tu sistema recibirá los eventos.
4. Selecciona los eventos que deseas escuchar.
5. Haz clic en Crear.
6. Se generará automáticamente un secreto HMAC individual para este webhook. Copia y guárdalo de forma segura.

Eventos disponibles

Puedes suscribirte a los siguientes eventos:

Evento	Se dispara cuando...
conversation_created	Se crea una nueva conversación
conversation_status_changed	Cambia el estado de una conversación (abierta, pendiente, pospuesta, resuelta)
conversation_updated	Se actualizan atributos de una conversación
message_created	Se envía o recibe un nuevo mensaje
message_updated	Se actualiza un mensaje existente
contact_created	Se crea un nuevo contacto
contact_updated	Se actualizan datos de un contacto
inbox_created	Se crea una nueva bandeja de entrada (canal)
inbox_updated	Se actualiza la configuración de una bandeja de entrada
webwidget_triggered	Un visitante interactúa con el widget web
conversation_typing_on	Un participante comienza a escribir en una conversación
conversation_typing_off	Un participante deja de escribir en una conversación

Formato del payload

Cada evento envía un payload en formato JSON con la siguiente estructura general:

{
  "event": "message_created",
  "id": "12345",
  "account": {
    "id": 1,
    "name": "Mi Empresa"
  },
  "data": {
    "id": 67890,
    "content": "Hola, necesito ayuda con mi pedido",
    "message_type": "incoming",
    "conversation": {
      "id": 456,
      "status": "open"
    },
    "sender": {
      "id": 789,
      "name": "Juan Perez",
      "type": "contact"
    },
    "created_at": "2025-01-15T10:30:00.000Z"
  }
}

Verificación HMAC

Para garantizar que los webhooks provienen de Zelta Chat, cada solicitud incluye estos encabezados HTTP:

Encabezado	Descripción
X-Zelta-Delivery	Identificador único (UUID) de esta entrega
X-Zelta-Timestamp	Marca de tiempo Unix (en segundos) usada en la firma (cuando el webhook tiene secreto)
X-Zelta-Signature	sha256= seguido del HMAC-SHA256 calculado sobre la cadena <timestamp>.<cuerpo>

Cada webhook tiene su propio secreto HMAC individual, lo que permite verificar la autenticidad de cada endpoint de forma aislada.

Para verificar la firma en tu servidor:

1. Toma el valor del encabezado X-Zelta-Timestamp.
2. Construye la cadena a firmar concatenando timestamp + . + el cuerpo crudo (raw body) de la solicitud.
3. Calcula HMAC-SHA256(secreto, "<timestamp>.<cuerpo>") en hexadecimal.
4. Antepón sha256= y compáralo (en tiempo constante) con el encabezado X-Zelta-Signature.

Importante

Siempre verifica la firma HMAC antes de procesar un webhook en tu servidor. Esto previene que actores malintencionados envíen solicitudes falsas a tu endpoint.

Tiempo de espera y reintentos

El tiempo de espera por solicitud (timeout) es de 5 segundos por defecto.

Para los webhooks de cuenta y de bandeja de entrada no hay reintentos automáticos: si tu endpoint falla o no responde a tiempo, ese evento se omite y no se vuelve a enviar (el fallo solo se registra).

Por eso, diseña tu receptor para:

• Responder con 2xx lo antes posible y procesar la lógica de forma asíncrona.
• Ser idempotente (usa el encabezado X-Zelta-Delivery para descartar entregas duplicadas).
• Tolerar entregas perdidas, reconciliando contra la API cuando el dato sea crítico.

Referencia técnica completa

Para los detalles de cada evento, el formato exacto de los payloads y ejemplos de verificación HMAC en Node.js y Ruby, consulta la .

Webhooks entrantes

Los webhooks entrantes permiten que sistemas externos envíen datos a Zelta Chat. Esto es útil para:

• Crear conversaciones desde formularios web externos.
• Actualizar datos de contactos desde tu CRM.
• Disparar acciones automatizadas desde otros sistemas.

Configurar un webhook entrante

1. Ve a Ajustes > Integraciones > Webhooks.
2. En la sección de webhooks entrantes, haz clic en + Crear endpoint.
3. Copia la URL del endpoint generada.
4. Configura tu sistema externo para enviar solicitudes HTTP POST a esa URL.

Gestión de webhooks

Ver webhooks configurados

Desde Ajustes > Integraciones > Webhooks puedes ver todos los webhooks activos con su URL, eventos suscritos y estado de la última entrega.

Editar un webhook

1. Haz clic en el webhook que deseas modificar.
2. Actualiza la URL o los eventos suscritos.
3. Haz clic en Actualizar.

Eliminar un webhook

1. Haz clic en el ícono de eliminar junto al webhook.
2. Confirma la eliminación.

Consejo

Usa herramientas como durante la fase de desarrollo para inspeccionar los payloads que envía Zelta Chat antes de implementar la lógica en tu servidor.

Casos de uso comunes

Caso de uso	Evento	Acción en tu sistema
Sincronizar contactos con CRM	contact_created	Crear registro en el CRM
Alertas de conversaciones críticas	conversation_created	Enviar alerta a canal interno
Análisis de mensajes	message_created	Procesar y almacenar en data warehouse
Encuestas post-atención	conversation_status_changed	Enviar encuesta cuando se resuelve