Webhooks de salida

Visión general

Los webhooks son el camino inverso de la API: en lugar de que su sistema le pregunte a ChatISP qué cambió, ChatISP avisa a su sistema cuando sucede. Usos típicos en un proveedor de internet:

• Registrar en el CRM cada atención cerrada, con protocolo y motivo, y obtener el historial por la API.
• Saber cuándo el cliente respondió a un aviso enviado por el ERP y activar una automatización.
• Seguir si el boleto enviado por WhatsApp fue entregado y leído.
• Reflejar las órdenes de servicio en el ERP y saber cuándo cambian de etapa o de responsable.
• Alimentar un panel propio con la cola y la distribución de las atenciones en tiempo real.

Cómo funciona

1. Usted registra un webhook con la dirección de su sistema y los eventos de interés.
2. Cuando ocurre un evento, ChatISP guarda la entrega en una cola. La atención nunca espera a su sistema: si está lento o fuera de servicio, nada cambia para el equipo ni para el cliente.
3. El servicio en segundo plano de ChatISP recorre la cola aproximadamente cada 20 segundos y hace los POST en paralelo, hasta 100 entregas por pasada. La entrega llega, en general, algunos segundos después del evento.
4. Su sistema verifica la firma, responde con HTTP 2xx y procesa el evento.
5. Si la respuesta no es 2xx, o la conexión falla, ChatISP intenta de nuevo más tarde, con espera creciente. Vea Reenvío y plazos.

Requisitos

• Plan con API pública y webhooks (PREMIUM, GOLD, ENTERPRISE o prueba) Recurso del plan. En otros planes, la tarjeta Webhooks aparece bloqueada.
• Permiso Integraciones en el perfil de acceso de quien registra.
• Una dirección HTTP o HTTPS que el servidor de ChatISP pueda alcanzar. En una instalación propia, el servidor necesita acceso de salida a esa dirección; en ChatISP Cloud, la dirección debe ser pública en internet.

No hay límite en la cantidad de webhooks. Un mismo evento se entrega a todos los webhooks activos suscritos a él, cada uno con su propia cola y sus propios intentos.

Registrar un webhook

1. En el menú lateral, abra Integraciones.
2. En la tarjeta Webhooks ("Avisos por HTTP a sistemas externos cuando algo ocurre en la atención."), haga clic en Nuevo webhook.
3. Complete el Nombre (hasta 120 caracteres), por ejemplo "CRM: atenciones".
4. En Dirección, informe la URL completa que recibirá los POST, comenzando con https:// (o http://), con hasta 500 caracteres.
5. Marque los eventos. En un webhook nuevo vienen marcados Mensaje recibido, Conversación creada y Conversación cerrada; los de volumen alto (Mensaje enviado y Entrega y lectura) quedan desmarcados hasta que los necesite. Al menos uno es obligatorio.
6. Haga clic en Guardar. La ventana Webhook creado muestra el Secreto, con el botón Copiar. Guárdelo en su sistema: con él se verifica la firma de cada entrega.

whsec_4b1e9a07c3d2f68e5a90b1c2d3e4f5a6

El secreto comienza con whsec_, seguido de 32 caracteres hexadecimales, y lo genera ChatISP.

La lista de webhooks

Editar, pausar y eliminar

• Editar cambia nombre, dirección y eventos, y muestra el interruptor Activo. El secreto no cambia.
• Desactivar Activo pausa el webhook: los eventos nuevos dejan de encolarse para él, y las entregas que ya estaban en la cola quedan guardadas, sin gastar intentos. Al reactivarlo, vuelven a salir.
• Eliminar pide confirmación ("¿Eliminar este webhook? Las entregas pendientes se descartarán.") y borra el webhook junto con su cola.

Eventos

Son 9 eventos, en el orden de la pantalla. El código es el valor que llega en el campo evento y en el encabezado X-ChatISP-Evento.

Además de estos, el botón Probar entrega el evento especial teste (vea Probar).

Lo que no genera evento

• Las notas internas del equipo y las notas registradas por la API (conversas/nota).
• La transferencia a un agente genera solo conversa_transferida, no conversa_atribuida. En cambio, la transferencia a un departamento con distribución automática activada puede generar ambos: primero conversa_transferida (hacia la cola) y después conversa_atribuida con "como": "roleta", cuando la distribución entrega la conversación a alguien.
• En las órdenes de servicio, la edición de título, descripción, prioridad, plazo o tipo, y los adjuntos, no generan ticket_atualizado. Abrir una OS que ya tiene responsable genera solo ticket_criado.
• El cierre automático de las conversaciones abiertas por campañas y por la regla de cobranza (la conversación nueva queda cerrada hasta que el cliente responda) no genera conversa_encerrada. El mismo cierre hecho por la API sí lo genera, con "motivo": "aviso".

Número gemelo

En un número conectado por QR y por la API oficial al mismo tiempo, el mismo mensaje del cliente puede llegar por los dos canales. ChatISP registra uno solo y emite un solo mensagem_recebida. Los eventos traen el conexao_id de la conversación, en general el de la conexión principal (vea Conexiones).

Formato de la entrega

Cada entrega es un POST a la dirección registrada, con cuerpo JSON en UTF-8:

POST /chatisp/webhook HTTP/1.1
Host: crm.suproveedor.com
Content-Type: application/json; charset=utf-8
X-ChatISP-Evento: conversa_encerrada
X-ChatISP-Entrega: 90412
X-ChatISP-Assinatura: sha256=5d2c0f1e8b7a69c4e3d21f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f2a1b0c

{"evento":"conversa_encerrada","emitido_em":"2026-10-01T10:05:12-03:00","dados":{...}}

Encabezados

Sobre del cuerpo

Respuesta esperada de su sistema

• Cualquier HTTP 2xx (200, 201, 202, 204) confirma la entrega. El cuerpo de la respuesta se ignora.
• Cualquier otro código (incluidas las redirecciones 3xx, que no se siguen), error de conexión, error de DNS o demora superior a 10 segundos cuenta como falla, y la entrega vuelve a la cola.
• ChatISP no rechaza un certificado autofirmado en su dirección. Aun así, use un certificado válido: el cuerpo lleva teléfono, nombre y contenido de los mensajes de sus clientes.

Datos de los eventos de mensaje

Resumen de la conversación (común a todos los eventos de mensaje y de conversación)

mensagem_recebida

El resumen de la conversación más el objeto mensagem:

{
  "evento": "mensagem_recebida",
  "emitido_em": "2026-10-01T09:12:41-03:00",
  "dados": {
    "conversa_id": 18342,
    "protocolo": "20261001-0042",
    "conexao_id": 1,
    "telefone": "5544999990000",
    "nome": "Maria Souza",
    "estado": "fila",
    "mensagem": {
      "id": 402850,
      "tipo": "texto",
      "conteudo": "Mi internet está caída desde temprano",
      "recebida_em": "2026-10-01T09:12:40-03:00"
    }
  }
}

mensagem_enviada

El resumen de la conversación más el objeto mensagem:

{
  "evento": "mensagem_enviada",
  "emitido_em": "2026-10-01T09:14:02-03:00",
  "dados": {
    "conversa_id": 18342,
    "protocolo": "20261001-0042",
    "conexao_id": 1,
    "telefone": "5544999990000",
    "nome": "Maria Souza",
    "estado": "humano",
    "mensagem": {
      "id": 402853,
      "autor": "atendente",
      "autor_nome": "Ana Ribeiro",
      "tipo": "texto",
      "conteudo": "¡Buenos días, Maria! Ya estoy revisando su señal.",
      "nome_arquivo": "",
      "status": "enviada",
      "erro": "",
      "enviada_em": "2026-10-01T09:14:02-03:00"
    }
  }
}

mensagem_status

El resumen de la conversación más un objeto mensagem corto. Solo sale cuando el status avanza (enviada a entregue, entregue a lida) o cuando el mensaje pasa a erro; los recibos repetidos o atrasados que no cambian nada no generan evento.

{
  "evento": "mensagem_status",
  "emitido_em": "2026-10-01T09:15:30-03:00",
  "dados": {
    "conversa_id": 18342,
    "protocolo": "20261001-0042",
    "conexao_id": 1,
    "telefone": "5544999990000",
    "nome": "Maria Souza",
    "estado": "humano",
    "mensagem": {
      "id": 402853,
      "status": "lida",
      "em": "2026-10-01T09:15:30-03:00"
    }
  }
}

Datos de los eventos de conversación

Todos comienzan con el resumen de la conversación descrito en Datos de los eventos de mensaje.

conversa_criada

Solo el resumen de la conversación. El estado es siempre fila: el evento sale en el instante de la creación, antes de que actúen el flujo, la IA o la distribución. Cuando quien la abre es el cliente, llega a continuación el mensagem_recebida del primer mensaje.

{
  "evento": "conversa_criada",
  "emitido_em": "2026-10-01T09:12:41-03:00",
  "dados": {
    "conversa_id": 18342,
    "protocolo": "20261001-0042",
    "conexao_id": 1,
    "telefone": "5544999990000",
    "nome": "Maria Souza",
    "estado": "fila"
  }
}

conversa_atribuida y conversa_transferida

Ambos traen el resumen de la conversación y quién la tiene después del cambio:

{
  "evento": "conversa_transferida",
  "emitido_em": "2026-10-01T09:20:15-03:00",
  "dados": {
    "conversa_id": 18342,
    "protocolo": "20261001-0042",
    "conexao_id": 1,
    "telefone": "5544999990000",
    "nome": "Maria Souza",
    "estado": "fila",
    "departamento_id": 2,
    "departamento": "Financiero",
    "atendente_id": null,
    "atendente": "",
    "detalhe": "Cola del departamento: Financiero"
  }
}

{
  "evento": "conversa_atribuida",
  "emitido_em": "2026-10-01T09:20:16-03:00",
  "dados": {
    "conversa_id": 18342,
    "protocolo": "20261001-0042",
    "conexao_id": 1,
    "telefone": "5544999990000",
    "nome": "Maria Souza",
    "estado": "humano",
    "departamento_id": 2,
    "departamento": "Financiero",
    "atendente_id": 9,
    "atendente": "Bruno Lima",
    "como": "roleta"
  }
}

conversa_encerrada

El resumen de la conversación (con estado encerrada) más el campo motivo:

{
  "evento": "conversa_encerrada",
  "emitido_em": "2026-10-01T10:05:12-03:00",
  "dados": {
    "conversa_id": 18342,
    "protocolo": "20261001-0042",
    "conexao_id": 1,
    "telefone": "5544999990000",
    "nome": "Maria Souza",
    "estado": "encerrada",
    "motivo": "Problema resuelto"
  }
}

Para obtener el historial y el resumen de la atención, llame a conversas/consultar o conversas/mensagens con el conversa_id. El resumen hecho por la IA se genera unos instantes después del cierre; si su sistema lo necesita, consulte con un pequeño retraso.

Datos de los eventos de orden de servicio

ticket_criado y ticket_atualizado traen el mismo resumen de la OS, ya con los valores después del cambio:

ticket_atualizado agrega:

{
  "evento": "ticket_criado",
  "emitido_em": "2026-10-01T09:25:40-03:00",
  "dados": {
    "ticket_id": 123,
    "numero": "OS-000123",
    "titulo": "Sin señal en la ONU: visita técnica",
    "etapa_id": 1,
    "etapa": "Nuevo",
    "natureza": "inicial",
    "prioridade": "alta",
    "origem": "ia",
    "conversa_id": 18342,
    "telefone": "5544999990000",
    "nome_cliente": "Maria Souza",
    "departamento_id": 1,
    "responsavel_id": null,
    "responsavel": "",
    "prazo_em": "2026-10-02T18:00:00-03:00"
  }
}

{
  "evento": "ticket_atualizado",
  "emitido_em": "2026-10-01T14:02:10-03:00",
  "dados": {
    "ticket_id": 123,
    "numero": "OS-000123",
    "titulo": "Sin señal en la ONU: visita técnica",
    "etapa_id": 3,
    "etapa": "En campo",
    "natureza": "andamento",
    "prioridade": "alta",
    "origem": "ia",
    "conversa_id": 18342,
    "telefone": "5544999990000",
    "nome_cliente": "Maria Souza",
    "departamento_id": 1,
    "responsavel_id": 12,
    "responsavel": "Diego Técnico",
    "prazo_em": "2026-10-02T18:00:00-03:00",
    "mudanca": "comentario",
    "comentario": "[API: Sistema de OS] OS 55821 abierta, técnico en camino."
  }
}

Cuando un usuario del panel mueve una OS sin dueño a una etapa de trabajo, pasa a ser el responsable automáticamente. En ese caso sale un único ticket_atualizado con mudanca etapa, ya con el responsavel completado.

Firma HMAC

Cualquier persona que descubra la dirección de su webhook puede intentar enviar POST falsos. La firma garantiza que la entrega vino de su ChatISP y que el cuerpo no fue alterado:

X-ChatISP-Assinatura = "sha256=" + hex( HMAC_SHA256( clave = secreto, mensaje = cuerpo_crudo ) )

• Secreto: el valor completo mostrado en la pantalla, incluido el prefijo whsec_.
• Cuerpo crudo: los bytes exactos recibidos, antes de cualquier decodificación. No decodifique y vuelva a codificar el JSON para calcularla: la nueva serialización cambia espacios, orden o escapes (ChatISP envía acentos y barras sin escape) y la firma deja de coincidir.
• Compare en tiempo constante (hash_equals en PHP, crypto.timingSafeEqual en Node.js, hmac.compare_digest en Python).
• Firma ausente o diferente: responda 401 y descarte.

<?php
$segredo  = getenv('CHATISP_WEBHOOK_SEGREDO');   // whsec_...
$corpo    = file_get_contents('php://input');       // cuerpo CRUDO
$recebida = $_SERVER['HTTP_X_CHATISP_ASSINATURA'] ?? '';
$esperada = 'sha256=' . hash_hmac('sha256', $corpo, $segredo);

if (!hash_equals($esperada, $recebida)) {
    http_response_code(401);
    exit;
}

$entrega = (int) ($_SERVER['HTTP_X_CHATISP_ENTREGA'] ?? 0);
$evento  = json_decode($corpo, true);

if ($evento['evento'] !== 'teste') {
    $pdo = new PDO(getenv('DB_DSN'), getenv('DB_USER'), getenv('DB_PASS'));
    // clave única en "entrega": la repetición de una entrega ya guardada se ignora
    $pdo->prepare('INSERT IGNORE INTO chatisp_eventos (entrega, evento, corpo) VALUES (?, ?, ?)')
        ->execute([$entrega, $evento['evento'], $corpo]);
}
http_response_code(200);   // responde ya; un proceso aparte trata la tabla

const express = require('express');
const crypto  = require('crypto');

const SEGREDO = process.env.CHATISP_WEBHOOK_SEGREDO;   // whsec_...
const app = express();

function assinaturaValida(corpo, cabecalho) {
  const esperada = 'sha256=' + crypto.createHmac('sha256', SEGREDO).update(corpo).digest('hex');
  const a = Buffer.from(esperada);
  const b = Buffer.from(cabecalho || '');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// express.raw mantiene el cuerpo como Buffer, sin decodificar
app.post('/chatisp/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  if (!assinaturaValida(req.body, req.get('X-ChatISP-Assinatura'))) {
    return res.sendStatus(401);
  }
  const entrega = req.get('X-ChatISP-Entrega');
  const evento  = JSON.parse(req.body.toString('utf8'));
  res.sendStatus(200);                     // responde antes de procesar
  setImmediate(() => tratar(entrega, evento));
});

app.listen(3000);

import hmac, hashlib, json, os
from flask import Flask, request

SEGREDO = os.environ["CHATISP_WEBHOOK_SEGREDO"].encode()   # whsec_...
app = Flask(__name__)

def assinatura_valida(corpo: bytes, cabecalho: str) -> bool:
    esperada = "sha256=" + hmac.new(SEGREDO, corpo, hashlib.sha256).hexdigest()
    return hmac.compare_digest(esperada, cabecalho or "")

@app.post("/chatisp/webhook")
def receber():
    corpo = request.get_data()   # bytes crudos, sin decodificar
    if not assinatura_valida(corpo, request.headers.get("X-ChatISP-Assinatura")):
        return "", 401
    entrega = request.headers.get("X-ChatISP-Entrega")
    evento = json.loads(corpo)
    enfileirar(entrega, evento)  # su cola (Redis, RQ, Celery, tabla...)
    return "", 200

Hay más receptores completos en Ejemplos prácticos.

Otras protecciones recomendadas

• Use HTTPS en la dirección del webhook.
• Use una ruta difícil de adivinar en la URL (por ejemplo /hooks/chatisp-8f2k1q) como capa adicional, nunca como sustituto de la firma.
• Para descartar entregas antiguas reenviadas por terceros, compare emitido_em con el reloj de su servidor, teniendo en cuenta que los nuevos intentos legítimos pueden llegar hasta unas 7 horas y media después del evento.
• Si su firewall solo permite orígenes conocidos, habilite la dirección IP de salida del servidor de ChatISP (en una instalación propia, su servidor; en ChatISP Cloud, consulte al soporte de Ravi Systems).

Reenvío y plazos

Cuando una entrega falla, ChatISP programa un nuevo intento con espera creciente. Son hasta 6 intentos en total:

Los tiempos pueden extenderse un poco, porque la cola se revisa aproximadamente cada 20 segundos y cada pasada entrega hasta 100 eventos. Si el 6.º intento también falla, la entrega se abandona y no vuelve más.

• Caída larga = eventos perdidos. Si su sistema queda fuera de servicio por más de unas 7 horas, las entregas de ese período se agotan. Después de una caída larga, concilie por la API: conversas/listar con atualizadas_desde y tickets/listar traen lo que cambió.
• Mantenimiento planificado: pause el webhook (interruptor Activo desactivado). Las entregas pendientes quedan congeladas sin gastar intentos y se reanudan al reactivar. Los eventos que ocurran durante la pausa no se encolan; concilie ese intervalo por la API.
• Siga la cola: el número destacado en la columna Último envío muestra cuántas entregas esperan. Un número en aumento es señal de que su sistema está rechazando o está fuera de servicio.

Idempotencia y orden

Duplicados

Una entrega puede llegar más de una vez. Ocurre cuando su sistema procesó el evento, pero la respuesta no llegó a tiempo (por ejemplo, respondió después de 10 segundos, o la conexión se cayó antes de la respuesta): ChatISP lo considera una falla e intenta de nuevo.

Use el encabezado X-ChatISP-Entrega como clave de idempotencia:

• Es el mismo en todos los intentos de la misma entrega, y el cuerpo también es idéntico.
• Es único por webhook: el mismo evento entregado a dos webhooks tiene números de entrega diferentes.
• Guarde los números ya procesados (basta una tabla con clave única, como en el ejemplo en PHP de arriba) e ignore los repetidos, respondiendo 200.

Como segunda línea de defensa, use los identificadores del propio evento: mensagem.id para mensajes, conversa_id junto con el tipo de evento para conversaciones, ticket_id para órdenes de servicio.

Orden de llegada

En condiciones normales, las entregas salen aproximadamente en el orden de los eventos (por ejemplo, conversa_criada antes del mensagem_recebida del primer mensaje). Pero no hay garantía: eventos del mismo segundo pueden salir en otro orden, y una entrega que falla y pasa a un nuevo intento es superada por las siguientes. Reglas prácticas:

• Ordene por emitido_em y por los ids, nunca por el orden de llegada.
• Para el estado actual de una conversación o una OS, no acumule los eventos: use el evento como disparador y consulte el estado en la API (conversas/consultar, tickets/consultar).
• En un mensagem_status, solo avance el status de su lado (enviada, entregue, lida); nunca vuelva de lida a entregue por un evento atrasado.

Probar y monitorear

Botón Probar

En la lista de webhooks, Probar hace en el momento una entrega del evento teste, fuera de la cola y sin nuevos intentos, con la misma firma y los mismos encabezados de las entregas reales (X-ChatISP-Entrega vale 0):

{"evento":"teste","emitido_em":"2026-10-01T08:30:00-03:00","dados":{"webhook_id":2}}

El resultado aparece en la pantalla:

• "Entrega de prueba aceptada (http 200)." cuando su sistema respondió 2xx.
• "La entrega de prueba falló (...)." con el código HTTP o el error de conexión, por ejemplo http 401 (la firma no coincidió de su lado) o un mensaje de tiempo agotado o de nombre no encontrado.

La prueba funciona incluso con el webhook inactivo y actualiza la columna Último envío. Su sistema debe responder 2xx al evento teste y no hacer nada con él.

Probar con eventos reales

1. Registre el webhook con los eventos deseados.
2. Envíe un mensaje desde un celular suyo al número del proveedor: llegan conversa_criada (si no había conversación abierta) y mensagem_recebida.
3. Responda desde el panel: llegan conversa_atribuida (al tomar la conversación), mensagem_enviada y, a continuación, mensagem_status con entregue y lida.
4. Transfiera y cierre la conversación para ver conversa_transferida y conversa_encerrada. Abra y mueva una OS para ver los eventos de orden de servicio.

Sin receptor listo

Para ver el formato real antes de programar, registre temporalmente la dirección de un servicio de inspección de solicitudes (del tipo "request bin") y haga clic en Probar. Después cámbiela por la dirección definitiva. No deje un servicio de terceros registrado en producción: las entregas reales llevan datos de sus clientes.

Eventos de volumen alto

mensagem_enviada y mensagem_status acompañan cada mensaje enviado por el proveedor, incluidos los de la IA, los flujos, las campañas y la regla de cobranza. Cada mensaje enviado genera un mensagem_enviada y normalmente uno o dos mensagem_status más (entregue y lida). Por eso vienen desmarcados en un webhook nuevo.

Capacidad de entrega

ChatISP entrega hasta 100 eventos por pasada de la cola, en paralelo, y la cola se recorre aproximadamente cada 20 segundos: algo del orden de 300 entregas por minuto, sumando todos los webhooks. Los picos por encima de eso no se pierden, pero forman cola y llegan con retraso. Ejemplo: una campaña de 1.000 mensajes con los dos eventos de volumen alto activados genera unas 3.000 entregas, que tardan alrededor de 10 minutos en salir; en ese intervalo, los eventos de conversación también esperan en la misma cola.

Recomendaciones

• Active mensagem_enviada y mensagem_status solo si su sistema realmente usa esa información (por ejemplo, para comprobar la entrega de un aviso de cobranza).
• Separe en webhooks diferentes los eventos de volumen alto y los de conversación y orden de servicio, apuntando a direcciones diferentes. Cada webhook tiene sus propios intentos, y el sistema que trata conversaciones y órdenes de servicio no necesita recibir ni descartar miles de recibos.
• Para confirmar la entrega de un envío hecho por la propia API, también se puede consultar el status del mensaje con conversas/mensagens en lugar de suscribirse a todos los recibos.
• Responda en milisegundos: con volumen alto, un receptor lento acumula fallas por tiempo agotado y sus entregas vuelven para un nuevo intento, llegando con retraso.

Buenas prácticas y problemas frecuentes

Lista de verificación del receptor

• Validar la firma con el cuerpo crudo, en tiempo constante.
• Responder 2xx rápido, muy por debajo de 10 segundos; procesar en una cola propia, en segundo plano.
• Descartar duplicados por el X-ChatISP-Entrega.
• Tratar el evento teste con 2xx y sin efecto.
• Ignorar eventos y campos desconocidos, para seguir funcionando si ChatISP agrega información.
• No depender del orden de llegada; consultar la API cuando necesite el estado actual.
• Suscribirse solo a los eventos necesarios y separar los de volumen alto.
• Usar HTTPS con certificado válido.

Problemas frecuentes