Webhooks

Visão geral

Existem dois fluxos independentes: outbound (a Prosalab envia eventos pra uma URL sua) e inbound (sistemas como n8n ou ActiveCampaign enviam dados pra uma URL da Prosalab).

Eventos outbound

A Prosalab dispara um POST assinado pra cada URL cadastrada, para cada evento ao qual ela está inscrita (webhook-dispatcher.ts:14-18).

{
  "event": "message.received",
  "timestamp": "2026-07-15T09:20:00.000Z",
  "company_id": "<uuid>",
  "delivery_id": "<uuid>",
  "data": {
    "message_id": "<uuid>",
    "type": "text",
    "content": "Oi, gostaria de saber o valor da consulta",
    "media_url": null,
    "media_mimetype": null,
    "media_caption": null,
    "direction": "inbound",
    "sender_type": "contact",
    "status": "received",
    "created_at": "2026-07-15T09:20:00.000Z",
    "contact": {
      "id": "<uuid>",
      "phone": "5548999990000",
      "name": "João Silva",
      "source_platform": "whatsapp",
      "is_ai_enabled": true,
      "external_ai_enabled": true
    },
    "connection": {
      "id": "<uuid>",
      "type": "whatsapp",
      "name": "Comercial"
    }
  }
}

Assinatura HMAC

Todo POST outbound carrega três headers de verificação (webhook-dispatcher.ts:167-173): X-Prosalab-Signature no formato sha256=<hex>, X-Prosalab-Event com o tipo do evento, e X-Prosalab-Delivery com um UUID único da entrega (útil pra deduplicar reentregas).

A assinatura é o HMAC-SHA256 do corpo BRUTO (a string exata enviada, sem re-serializar) usando o secret do webhook, em hexadecimal (webhook-dispatcher.ts:86-88, 159, 169). Re-serializar o JSON antes de validar pode reordenar chaves e quebrar a comparação — sempre valide sobre o texto bruto recebido, nunca sobre JSON.stringify(JSON.parse(rawBody)).

import { createHmac, timingSafeEqual } from 'crypto';

function isValidSignature(rawBody: string, signatureHeader: string, secret: string): boolean {
  // rawBody = o corpo EXATO recebido (string bruta, antes de qualquer parse/re-stringify)
  const expectedHex = createHmac('sha256', secret).update(rawBody).digest('hex');
  const expected = `sha256=${expectedHex}`;

  const a = Buffer.from(signatureHeader);
  const b = Buffer.from(expected);
  if (a.length !== b.length) return false; // timingSafeEqual exige mesmo tamanho

  return timingSafeEqual(a, b);
}

// Uso num handler Express/Next:
// const rawBody = await request.text();
// const signature = request.headers.get('x-prosalab-signature') ?? '';
// const secret = process.env.MEU_WEBHOOK_SECRET!; // o secret cadastrado nesse webhook
// if (!isValidSignature(rawBody, signature, secret)) {
//   return new Response('Assinatura inválida', { status: 401 });
// }

Retentativas

Quando a entrega falha (timeout, erro de rede ou resposta HTTP fora da faixa 2xx), a Prosalab reagenda automaticamente com backoff crescente, até 5 tentativas no total (webhook-dispatcher.ts:238-244): 30 segundos → 2 minutos → 10 minutos → 30 minutos (4 retentativas após a entrega inicial). Depois da última tentativa sem sucesso, a entrega é marcada como failed.

Inbound de contatos

Sistemas externos (n8n, ActiveCampaign) podem enviar dados de contato pra Prosalab via POST /api/webhooks/incoming/{slug}, onde {slug} identifica um endpoint específico cadastrado na sua conta. A Prosalab aplica o variable_mapping configurado (chaves canônicas → JSONPath no payload recebido) e faz upsert do contato por telefone (route.ts:1-22, 138-146; webhook-inbound.types.ts:23-35).

Chaves canônicas reconhecidas no mapeamento: first_name (alias name) e phone_number (alias phone, obrigatório pra localizar/criar o contato). Exemplo de variable_mapping: { "first_name": "$.contact.firstname", "phone_number": "$.contact.phone" } (webhook-inbound.types.ts:30).

{
  "contact": {
    "firstname": "João",
    "phone": "5548999990000"
  }
}

{
  "ok": true,
  "contact_id": "<uuid>",
  "action": "created",
  "custom_fields_captured": 0,
  "new_pending_definitions": []
}

Disparo de template

Sistemas externos disparam um template Meta-aprovado pra um número específico via POST /api/webhooks/template-dispatch/{token}, onde {token} é o UUID v4 único do template (o próprio token funciona como segredo — não é exigido header adicional) (template-dispatch/route.ts:1-28).

Os dados podem vir de duas formas: corpo JSON (recomendado, ex.: n8n) ou query-string (pensado pra ferramentas como ActiveCampaign, que postam form-data e usam tags de personalização na URL). Quando o corpo é um JSON válido, ele tem precedência sobre a query-string (route.ts:97-134).

{
  "phone_number": "5548999990000",
  "variables": {
    "1": "João",
    "2": "Consulta de avaliação"
  }
}

POST /api/webhooks/template-dispatch/3f2a9c1e-...-b7d4?phone=5548999990000&v1=Jo%C3%A3o&v2=Consulta+de+avalia%C3%A7%C3%A3o HTTP/1.1

{
  "ok": true,
  "wamid": "wamid.HBgL...",
  "contact_id": "<uuid>",
  "message_id": "<uuid>",
  "action": "sent"
}