Visão geral dos webhooks

Com webhooks, a TopTalking avisa o seu sistema quando algo acontece na conta — sem você precisar consultar a API o tempo todo. Cada evento é um POST com JSON para um endereço HTTPS seu, assinado com HMAC-SHA256.

Exemplos de uso:

• Gravar no seu banco cada mensagem recebida (message.received).
• Atualizar o CRM quando um card muda de etapa no Kanban (contact.stage_changed).
• Saber quando uma mensagem foi entregue ou lida (message.status_updated).
• Avisar a equipe quando um lembrete agendado falhar (scheduled_message.failed).
• Saber na hora que um WhatsApp foi conectado pelo QR Code — ou que caiu (channel.status_updated).
• Acompanhar a aprovação e o envio de uma campanha (campaign.status_updated).

A lista completa, com exemplos de JSON, está em Eventos e payloads.

Configurar no painel

1. Abra Configurações → Desenvolvedor e vá até o cartão Webhooks.
2. Clique em Novo webhook.
3. Informe a URL do seu sistema (HTTPS), uma descrição e escolha os eventos — ou Todos os eventos.
4. Copie o segredo de assinatura (whsec_...) e guarde como variável de ambiente no seu servidor (ex.: TOPTALKING_WEBHOOK_SECRET). Você vai usá-lo para verificar a assinatura.
5. No menu do webhook, clique em Enviar teste. O seu endpoint deve receber um evento ping e responder 2xx.
6. Em Ver entregas, confira o status HTTP e o tempo de resposta de cada envio.

Prefere automatizar? Dá para fazer tudo pela API: veja Webhooks (gestão).

Requisitos do endereço

• HTTPS com certificado válido.
• Público na internet: localhost, IPs de rede interna e endereços .local não recebem eventos. Para testar na sua máquina, use um túnel HTTPS (como ngrok ou Cloudflare Tunnel).
• Até 10 webhooks por organização. Cada um pode assinar eventos diferentes.

Como chega um evento

POST /webhooks/toptalking HTTP/1.1
Host: meusistema.com.br
Content-Type: application/json
User-Agent: TopTalking-Webhooks/1.0
X-TopTalking-Signature: t=1794409800,v1=946dcacfdaee2f0eca7a2194d9919092cac50f554189d6651b1ce5acca155cdc
X-TopTalking-Event: ping
X-TopTalking-Event-Id: 252a2c18-7b60-47a6-9feb-9c8322f2ba50
X-TopTalking-Delivery-Id: d94d8ee3-4eb6-41f1-8c44-44bd0907d99f

{"id":"252a2c18-7b60-47a6-9feb-9c8322f2ba50","object":"event","type":"ping","created_at":"2026-11-11T15:10:00Z","organization_id":"e044a615-e879-44bb-8510-948b10b5e93c","data":{"webhook_id":"f03b0773-5912-4a45-9139-c29375485843","message":"Evento de teste enviado pela TopTalking."}}

Cabeçalho	Descrição
Content-Type	Sempre application/json.
User-Agent	TopTalking-Webhooks/1.0.
X-TopTalking-Signature	t=<timestamp unix em segundos>,v1=<assinatura em hex>. Veja Verificar a assinatura.
X-TopTalking-Event	O tipo do evento (ex.: message.received).
X-TopTalking-Event-Id	ID do evento. É o mesmo em todas as retentativas — use para não processar duas vezes.
X-TopTalking-Delivery-Id	ID da entrega para este endereço.

O corpo (envelope)

Todo evento tem o mesmo envelope; o conteúdo muda em data:

{
  "id": "597b7d23-208d-4b5b-82a2-fb1703a81d63",
  "object": "event",
  "type": "message.received",
  "created_at": "2026-11-11T14:12:40Z",
  "organization_id": "e044a615-e879-44bb-8510-948b10b5e93c",
  "data": {
    "message": { "...": "..." },
    "contact": { "...": "..." }
  }
}

Campo	Descrição
id	ID do evento (igual ao cabeçalho X-TopTalking-Event-Id).
object	Sempre event.
type	Tipo do evento.
created_at	Quando o evento aconteceu.
organization_id	Organização de origem.
data	Os dados do evento. Veja Eventos e payloads.

Como responder

• Responda com qualquer status 2xx em até 10 segundos. O corpo da resposta é ignorado.
• Valide a assinatura antes de tudo e responda 401 se ela não bater.
• Faça o trabalho pesado depois de responder (fila, job em segundo plano). Se você demorar mais de 10 segundos ou responder fora de 2xx, a TopTalking considera falha e tenta de novo.
• Seja idempotente: o mesmo evento pode chegar mais de uma vez. Guarde os id já processados.
• Não dependa da ordem de chegada: use created_at e os dados do próprio evento.

Esqueleto de um receptor (Node.js + Express)

import express from 'express';
import { verificarAssinatura } from './toptalking-assinatura.js'; // veja "Verificar a assinatura"

const app = express();

// Importante: o corpo CRU (sem JSON.parse) é necessário para validar a assinatura.
app.post('/webhooks/toptalking', express.raw({ type: 'application/json' }), async (req, res) => {
  if (!verificarAssinatura(req.body, req.get('X-TopTalking-Signature'), process.env.TOPTALKING_WEBHOOK_SECRET)) {
    return res.status(401).send('assinatura inválida');
  }

  const evento = JSON.parse(req.body.toString('utf8'));

  // Responda rápido; processe depois.
  res.sendStatus(200);

  await filaDeEventos.adicionar(evento); // sua fila / job em segundo plano
});

app.listen(3000);

Eventos e payloadsTodos os eventos com exemplos de JSON.

Verificar a assinaturaCódigo pronto para Node.js, Python e Supabase Edge Functions.

Entregas e novas tentativasPrazos, retentativas, desativação automática e histórico.

Receber webhooks no LovableEdge Function que valida a assinatura e salva numa tabela.