Webhooks de Chat en Vivo

Los webhooks permiten que onWebChat envíe eventos a tu servidor en tiempo real. Cada vez que ocurre algo en un chat: se inicia una conversación, se envía un mensaje, se cierra o valora un chat, o se deja un mensaje offline, enviamos un HTTP POST con un cuerpo JSON a una URL que tú eliges.

Es la forma más sencilla de sincronizar las transcripciones de chat en tu CRM o CMS, disparar emails de seguimiento, crear informes personalizados o notificar otro sistema, sin polling.

Los webhooks están disponibles en todos los planes de pago. Cada entrega está firmada para que puedas verificar que realmente proviene de onWebChat.



POST https://your-server.com/onwebchat-webhook
Content-Type: application/json
X-OWC-Event: chat.closed
X-OWC-Delivery: 9381
X-OWC-Signature: sha256=4f1c...c2a9

{ "event": "chat.closed", "siteid": 1234, ... }

Configurar Webhooks

Abre tu panel y ve a Configuración → Webhooks. Haz clic en "Añadir endpoint", pega la URL que debe recibir los eventos, elige qué eventos deseas (o selecciona "Todos los eventos") y guarda.

Al crear un endpoint generamos un secreto de firma. Usarás este secreto para verificar las solicitudes entrantes (ver Verificar Firmas). Puedes regenerarlo en cualquier momento.

Puedes añadir múltiples endpoints por sitio web y revisar las entregas recientes, incluyendo el estado HTTP, número de intentos y cualquier error, directamente en el panel.



/* Dashboard → Settings → Webhooks */

URL      : https://your-server.com/onwebchat-webhook
Events   : chat.closed, message.created
Secret   : whsec_3f9a...   (used to verify requests)
Status   : Enabled

Tipos de Evento

Suscríbete a cualquier combinación de los eventos. Cada mensaje lleva una etiqueta "author" de visitor, agent, ai o trigger, por lo que el mismo evento message.created cubre conversaciones gestionadas por tu equipo y por el chatbot de IA.

Evento	Se envía cuando
`chat.created`	Se inicia un nuevo chat por un visitante, un trigger, el chatbot de IA o un agente.
`chat.assigned`	Un agente asume una conversación: la toma, releva al bot de IA o acepta una transferencia.
`message.created`	Se envía un nuevo mensaje en un chat. Incluye mensajes del visitante, un agente y el chatbot de IA.
`chat.closed`	Un chat termina. El payload incluye la transcripción completa, detalles del visitante y etiquetas.
`chat.rated`	Un visitante valora un chat.
`offline_message.created`	Un visitante envía el formulario offline mientras no hay agentes disponibles.
`visitor.updated`	Un agente actualiza el nombre, correo electrónico, teléfono o notas del visitante desde el panel.
`visitor.banned`	Un agente bloquea a un visitante desde el panel.
`visitor.unbanned`	Un agente desbloquea a un visitante previamente bloqueado desde el panel.

Formato del Payload

Cada webhook es un objeto JSON con el mismo sobre: el nombre del evento, tu siteid, una marca de tiempo ISO-8601 y un objeto de datos cuya forma depende del evento.

El ejemplo muestra un payload de chat.closed, que contiene la conversación completa. Eventos más pequeños como message.created o chat.rated incluyen solo los campos relevantes.


{
  "event": "chat.closed",
  "siteid": 1234,
  "created_at": "2026-06-22T07:40:52.322Z",
  "data": {
    "chat_id": 1206836,
    "started_at": "22-06-2026 10:40",
    "closed_at": "2026-06-22T07:40:52.322Z",
    "visitor": {
      "name": "Sarah Chen",
      "email": "sarah@example.com",
      "phone": "",
      "country": "United States",
      "os": "Windows 10",
      "browser": "Chrome 149.0"
    },
    "agents": ["Alex"],
    "labels": [{ "name": "sales", "color": "#4caf50" }],
    "messages": [
      { "author": "visitor", "text": "pricing info please", "time": "10:40" },
      { "author": "ai", "text": "Here is a quick overview...", "time": "10:40" }
    ]
  }
}

Verificar Firmas

Cada solicitud incluye una cabecera X-OWC-Signature con un hash HMAC-SHA256 del cuerpo bruto exacto de la solicitud, calculado con el secreto de firma de tu endpoint.

Para verificar una solicitud, calcula el HMAC-SHA256 del cuerpo bruto con tu secreto y compáralo con el valor de la cabecera (la parte después de "sha256="). Usa una comparación en tiempo constante y siempre hashea el cuerpo bruto.

También recibes X-OWC-Event (el nombre del evento) y X-OWC-Delivery (un id único para idempotencia).


// Node.js / Express
const crypto = require('crypto');

app.post('/onwebchat-webhook',
  express.raw({ type: '*/*' }), (req, res) => {

  const secret = 'whsec_your_secret';
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(req.body)              // raw Buffer
    .digest('hex');

  const got = req.headers['x-owc-signature'] || '';

  // constant-time compare; guard length first (timingSafeEqual throws on mismatch)
  const a = Buffer.from(got), b = Buffer.from(expected);
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return res.status(401).end();

  const payload = JSON.parse(req.body.toString());
  // ... handle payload.event ...
  res.sendStatus(200);
});

Verificar en PHP

La misma comprobación en PHP: lee el cuerpo bruto, recalcula el HMAC con tu secreto y compara con hash_equals().


<?php
$secret  = 'whsec_your_secret';
$payload = file_get_contents('php://input');
$got     = $_SERVER['HTTP_X_OWC_SIGNATURE'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $payload, $secret);

if (!hash_equals($expected, $got)) {
    http_response_code(401);
    exit;
}

$event = json_decode($payload, true);
// ... handle $event['event'] ...
http_response_code(200);

Reintentos y Desactivación Automática

Tu endpoint debe responder con un estado 2xx lo más rápido posible. Cualquier respuesta no-2xx, timeout o error de conexión se trata como un fallo.

Las entregas fallidas se reintentarán con un retraso creciente: después de 1 minuto, 5 minutos, 20 minutos, 1 hora y 2 horas.

Si un endpoint sigue fallando (5 fallos consecutivos), se desactiva automáticamente y se notifica al propietario del sitio. Reactívalo desde el panel. Devolver HTTP 410 lo desactiva inmediatamente.



    Attempt 1  → immediately
    Attempt 2  → after  1 minute
    Attempt 3  → after  5 minutes
    Attempt 4  → after 20 minutes
    Attempt 5  → after  1 hour
    Attempt 6  → after  2 hours

    5 failures in a row → endpoint disabled

Buenas Prácticas

Siempre verifica el X-OWC-Signature antes de confiar en un payload.
Responde 2xx rápido, luego realiza el trabajo pesado de forma asíncrona para no agotar el tiempo.
Usa X-OWC-Delivery para deduplicar, ya que la misma entrega puede reintentarse tras un fallo transitorio.
Sirve tu endpoint sobre HTTPS.
Ignora los tipos de eventos desconocidos para que nuevos eventos no rompan tu integración.

¿Listo para empezar? Ver planes o abre Configuración → Webhooks en tu panel.