Webhooks

Los webhooks te permiten recibir notificaciones HTTP cuando ocurren eventos en tus asistentes. Tiempo Real

Cómo Funcionan los Webhooks

Registra una URL de endpoint

Proporciona una URL donde podamos enviar notificaciones.
Elige los eventos

Selecciona qué eventos quieres recibir.
Recibe solicitudes POST

Enviamos datos JSON cuando ocurren eventos.
Responde con 200

Confirma la recepción con un código de estado éxito.

Configurando Webhooks

Ve a Configuración de API

Navega a Configuración → API → Webhooks
Haz clic en Agregar Webhook

Crea una nueva configuración de webhook.
Ingresa tu URL de endpoint

Proporciona la URL donde recibirás los eventos.
Selecciona los eventos

Elige qué eventos deben disparar el webhook.
Guarda y prueba

Guarda la configuración y envía un evento de prueba.

Tipos de Eventos

Evento	Descripción
`conversation.started`	Nueva conversación iniciada
`conversation.ended`	Conversación cerrada
`message.received`	Nuevo mensaje del usuario
`message.sent`	Respuesta del bot enviada
`escalation.requested`	Usuario solicitó humano

Evento	Descripción
`bot.created`	Nuevo bot creado
`bot.updated`	Configuración del bot cambiada
`bot.deleted`	Bot eliminado
`bot.trained`	Entrenamiento del bot completado

Evento	Descripción
`contact.created`	Nuevo contacto agregado
`contact.updated`	Contacto modificado
`lead.created`	Nuevo lead creado
`appointment.booked`	Cita programada
`appointment.cancelled`	Cita cancelada

Formato de Payload

Todos los webhooks envían datos JSON con esta estructura:

{
  "id": "evt_abc123",
  "type": "message.received",
  "created_at": "2024-01-15T10:30:00Z",
  "data": {
    "bot_id": "bot_xyz789",
    "session_id": "session_123",
    "message": {
      "id": "msg_456",
      "content": "Hola, necesito ayuda",
      "role": "user",
      "created_at": "2024-01-15T10:30:00Z"
    },
    "contact": {
      "id": "contact_789",
      "email": "[email protected]",
      "name": "Juan García"
    }
  }
}

Verificando Webhooks

Cada solicitud de webhook incluye una cabecera de firma:

X-Webhook-Signature: sha256=abc123...

Node.js
Python

const crypto = require('crypto');

function verificarWebhook(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  const expected = `sha256=${expectedSignature}`;
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// En tu manejador de endpoint
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const payload = JSON.stringify(req.body);

  if (!verificarWebhook(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Firma inválida');
  }

  // Procesar el webhook
  console.log('Webhook recibido:', req.body.type);
  res.status(200).send('OK');
});

import hmac
import hashlib

def verificar_webhook(payload, signature, secret):
    expected = 'sha256=' + hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

# En tu endpoint de Flask/Django
@app.route('/webhook', methods=['POST'])
def manejar_webhook():
    signature = request.headers.get('X-Webhook-Signature')
    payload = request.get_data(as_text=True)

    if not verificar_webhook(payload, signature, WEBHOOK_SECRET):
        return 'Firma inválida', 401

    # Procesar el webhook
    data = request.json
    print(f"Webhook recibido: {data['type']}")
    return 'OK', 200

Política de Reintentos

Reintentos Automáticos

Reintentamos webhooks fallidos hasta 5 veces.

Backoff Exponencial

Los reintentos ocurren a 1m, 5m, 30m, 2h, 24h.

Umbral de Fallo

Después de 5 fallos, el webhook se desactiva.

Probando Webhooks

Usa un endpoint de prueba

Herramientas como webhook.site te permiten inspeccionar solicitudes.
Envía eventos de prueba

Usa el botón “Enviar Prueba” en el panel de control.
Verifica la recepción

Revisa que tu endpoint recibió los datos correctamente.
Prueba el manejo de errores

Asegúrate de que tu endpoint maneje fallos con gracia.

Temas Relacionados

API de Chat Endpoints principales de chat

Autenticación Seguridad de claves API