Webhooks de Chat ao Vivo

Os webhooks permitem que o onWebChat envie eventos para o seu servidor em tempo real. Sempre que algo acontece num chat: uma nova conversa começa, é enviada uma mensagem, um chat é encerrado, avaliado, ou é deixada uma mensagem offline, enviamos um HTTP POST com um corpo JSON para um URL à sua escolha.

Esta é a forma mais fácil de sincronizar transcrições de chat no seu CRM ou CMS, acionar emails de acompanhamento, criar relatórios personalizados ou notificar outro sistema, sem polling.

Os webhooks estão disponíveis em todos os planos pagos. Cada entrega é assinada para que possa verificar que realmente veio do 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

Abra o seu painel e vá a Definições → Webhooks. Clique em "Adicionar endpoint", cole o URL que deve receber os eventos, escolha quais eventos pretende (ou selecione "Todos os eventos") e guarde.

Quando cria um endpoint geramos um segredo de assinatura. Usará este segredo para verificar os pedidos recebidos (ver Verificar Assinaturas). Pode regenerá-lo a qualquer momento.

Pode adicionar múltiplos endpoints por website e rever as entregas recentes, incluindo o estado HTTP, número de tentativas e qualquer erro, diretamente no painel.



/* 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

Subscreva qualquer combinação dos eventos abaixo. Cada mensagem tem uma etiqueta "author" de visitor, agent, ai ou trigger, pelo que o mesmo evento message.created cobre conversas geridas pela sua equipa e pelo chatbot de IA.

Evento	Enviado quando
`chat.created`	Um novo chat é iniciado por um visitante, um trigger, o chatbot de IA ou um agente.
`chat.assigned`	Um agente assume uma conversa: atende, assume do bot de IA ou aceita uma transferência.
`message.created`	Uma nova mensagem é enviada num chat. Inclui mensagens do visitante, de um agente e do chatbot de IA.
`chat.closed`	Um chat termina. O payload inclui a transcrição completa, detalhes do visitante e etiquetas.
`chat.rated`	Um visitante avalia um chat.
`offline_message.created`	Um visitante submete o formulário offline enquanto não há agentes disponíveis.
`visitor.updated`	Um agente atualiza o nome, email, telefone ou notas do visitante a partir do painel.
`visitor.banned`	Um agente bloqueia um visitante a partir do painel.
`visitor.unbanned`	Um agente desbloqueia um visitante previamente bloqueado a partir do painel.

Formato do Payload

Cada webhook é um objeto JSON com o mesmo envelope: o nome do evento, o seu siteid, um timestamp ISO-8601 e um objeto de dados cuja forma depende do evento.

O exemplo mostra um payload chat.closed, que contém a conversa completa. Eventos menores como message.created ou chat.rated incluem apenas os 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 Assinaturas

Cada pedido inclui um cabeçalho X-OWC-Signature com um hash HMAC-SHA256 do corpo bruto exato do pedido, calculado com o segredo de assinatura do seu endpoint.

Para verificar um pedido, calcule o HMAC-SHA256 do corpo bruto com o seu segredo e compare-o com o valor do cabeçalho (a parte após "sha256="). Use uma comparação em tempo constante e faça sempre o hash do corpo bruto.

Também recebe X-OWC-Event (o nome do evento) e X-OWC-Delivery (um id único para idempotência).


// 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 em PHP

A mesma verificação em PHP: leia o corpo bruto, recalcule o HMAC com o seu segredo e compare com 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);

Tentativas & Desativação Automática

O seu endpoint deve responder com um estado 2xx o mais rapidamente possível. Qualquer resposta não-2xx, timeout ou erro de ligação é tratado como falha.

As entregas falhadas são reprocessadas com atraso crescente: após 1 minuto, 5 minutos, 20 minutos, 1 hora e 2 horas.

Se um endpoint continuar a falhar (5 falhas consecutivas), é automaticamente desativado e o proprietário do site é notificado. Reative-o no painel. Devolver HTTP 410 desativa imediatamente.



    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

Boas Práticas

Verifique sempre o X-OWC-Signature antes de confiar num payload.
Responda 2xx rapidamente, depois faça o trabalho pesado de forma assíncrona para não exceder o tempo.
Use X-OWC-Delivery para deduplicar, pois a mesma entrega pode ser reprocessada após uma falha transitória.
Sirva o seu endpoint sobre HTTPS.
Ignore tipos de eventos desconhecidos para que novos eventos não quebrem a sua integração.

Pronto para começar? Ver planos ou abra Definições → Webhooks no seu painel.