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
webwidget_triggered	Un visitante interactúa con el widget web

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 una firma HMAC en el encabezado HTTP:

Encabezado	Descripción
X-Zelta-Signature	Firma HMAC-SHA256 del payload usando el secreto individual del webhook

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. Obtén el secreto individual desde la configuración del webhook en Zelta Chat.
2. Calcula el HMAC-SHA256 del cuerpo de la solicitud usando ese secreto.
3. Compara el resultado con el valor del 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.

Reintentos

Si tu servidor no responde con un código HTTP 2xx dentro de los primeros 5 segundos, Zelta Chat reintentará el envío:

Intento	Espera
1er reintento	1 minuto después
2do reintento	5 minutos después
3er reintento	30 minutos después

Después de 3 reintentos fallidos, el evento se descarta. Puedes consultar el historial de entregas desde la configuración del webhook.

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