Webhooks

A Onvox AI pode notificar seu sistema via POST assinado quando uma análise é concluída — seja via upload de áudio/texto colado na UI, via POST /api/analyses (API externa, pra quem integra por código e quer o resultado de volta assim que fica pronto), ou vinda de uma coleta de integração (PABX Onvox/Yeastar, Google Meet). Essa terceira origem é configurável por destino, via os gatilhos descritos em Quando o webhook dispara. Cada destino é atrelado a um papel (role), que define quais campos o payload carrega. Os papéis disponíveis no cadastro são os de administrador, então o destino recebe o dossiê completo, no escopo da empresa inteira — ver Por que só papel de administrador. Quantos destinos você cadastra é com você: não há teto.

Quando o webhook dispara

Quem decide é a sua empresa, destino a destino. Cada webhook carrega uma lista de gatilhos, e o evento só é enviado para os destinos que aceitam a origem daquela análise.

Um webhook novo nasce com os dois primeiros marcados. Esse é o comportamento que a plataforma sempre teve, e ele foi preservado: nenhum destino já existente passou a receber coisa nova sem alguém marcar.

Configurar um webhook

Configuração é restrita a admin_company e super_admin, na tela Configurações → Webhooks de Análise do painel. Uma empresa pode cadastrar quantos destinos quiser, inclusive vários no mesmo papel — é comum ter dois admin_company, um apontando para o BI interno e outro para o n8n. Não há teto de quantidade; há teto de papel: só os dois de administrador podem ser cadastrados, pelo motivo explicado em Por que só papel de administrador.

O único cadastro recusado é o duplicado exato: mesma empresa, mesmo papel e mesma URL. Dois destinos idênticos receberiam o mesmo conteúdo duas vezes, sem ganho nenhum. A mesma URL em papéis diferentes é permitida (ela receberia dois corpos diferentes, um por papel), e nada impede vários destinos do mesmo papel apontando para URLs diferentes.

Ao criar ou editar um destino você escolhe:

• o nome (opcional, até 80 caracteres), só para diferenciar destinos do mesmo papel na lista. Em branco, a tela mostra o endereço do destino no lugar;
• o papel, que define quais campos o payload carrega (ver Payload por papel);
• os gatilhos, que definem quais análises chegam ali (ver Quando o webhook dispara).

Os gatilhos de coleta ficam desabilitados enquanto o papel escolhido não for de administrador, pela razão explicada acima.

Resposta da tela ao criar (mesmo contrato do tRPC; o segredo só aparece AGORA, nunca mais):

{
  "result": {
    "data": {
      "id": "wh_abc123",
      "role": "admin_company",
      "label": "n8n produção",
      "triggers": ["manual_ui", "external_api"],
      "targetUrl": "https://seusistema.com/webhooks/onvox",
      "isActive": true,
      "createdAt": "2026-09-18T12:00:00.000Z",
      "updatedAt": "2026-09-18T12:00:00.000Z",
      "secret": "8f1e2a9c...64 chars hex (guarde agora)"
    }
  }
}

Por que só papel de administrador

Os papéis oferecidos no cadastro são os dois de administrador (admin_company e super_admin). Um destino com papel de vendedor ou supervisor é recusado.

O papel de um webhook reduz os campos do payload, não as linhas. Um destino de vendedor ou supervisor receberia as análises de toda a empresa — inclusive de gente que esse mesmo usuário não enxerga pela tela. Enquanto não existir escopo por linha, o destino fica onde papel e visibilidade já coincidem: o escopo da empresa.

Quantidade é outra coisa. Não há teto de destinos: cadastre quantos precisar, inclusive vários no mesmo papel. O que não existe é destino de uma pessoa.

Preciso separar por vendedor, time ou unidade

Isso o webhook não faz: todo destino recebe as análises da empresa inteira. A separação acontece no seu próprio fluxo (n8n, Make, sua API, seu backend) — e você não perde informação nenhuma, porque o evento já diz de quem é a análise. Se o objetivo for só mandar o mesmo evento para dois sistemas, aí não precisa de nada disso: cadastre dois destinos.

Estes campos viajam em todo evento, para todo destino de papel administrador (um destino legado de vendedor ou supervisor recebe só data.salespersonName; os outros três não existem no payload dele):

Concretamente. O POST que chega no seu endpoint tem esta cara (dossiê abreviado, os campos de roteamento em destaque):

{
  "event": "analysis.completed",
  "analysisId": "an_9f8e7d6c",
  "role": "admin_company",
  "data": {
    "id": "an_9f8e7d6c",
    "status": "completed",
    "source": "onvox",
    "displayScore": 87,
    "summary": "Cliente demonstrou interesse, mas pediu prazo para decidir.",

    "salespersonId": "user_123",
    "salespersonName": "Helena Pereira",
    "externalOwnerId": "1018",
    "externalCallId": "1784291064.69"
  }
}

Daí em diante a separação é sua. Em n8n, um nó Switch com uma saída por regra:

Ou, se preferir código, no seu próprio handler:

const DESTINOS = {
  user_123: 'https://crm.interno/equipe-a',
  user_456: 'https://crm.interno/equipe-b',
};

app.post('/webhooks/onvox', express.raw({ type: 'application/json' }), (req, res) => {
  const rawBody = req.body.toString('utf8');
  verifyOnvoxAiWebhook(/* ... ver "Verificar a assinatura" abaixo ... */);

  const { data } = JSON.parse(rawBody);
  const destino = DESTINOS[data.salespersonId];   // ou data.externalOwnerId
  if (destino) {
    encaminhar(destino, data);
  }
  res.status(200).send('ok');
});

O evento: analysis.completed

Todo POST carrega o mesmo envelope:

{
  "event": "analysis.completed",
  "analysisId": "an_9f8e7d6c",
  "role": "admin_company",
  "data": { "...": "payload escopado pelo papel (ver abaixo)" }
}

Payload por papel

O campo data usa exatamente o mesmo contrato de lib/analysis-output.ts já usado pela API (analysis.getPublic vs analysis.getById).

A equivalência com "o que aquele papel veria numa chamada autenticada" vale para os campos — o formato do dossiê é o mesmo. Ela não vale para quais análises chegam ali: o destino pertence à empresa, não a uma pessoa, e recebe todas as análises concluídas da empresa que casem com os gatilhos configurados. Como o papel de um destino é sempre de administrador, escopo de campo e escopo de linha coincidem: dossiê completo, empresa inteira.

O bloco onvox (telefonia: quem ligou, pra quem, gravação) faz parte do dossiê público (analysisPublicSchema, herdado por todos os papéis): quando a análise que disparou o evento carrega dados de telefonia, data.onvox aparece no payload de qualquer papel, inclusive nos destinos legados. Os identificadores de integração (provider, externalCallId, externalOwnerId) ficam reservados a admin_company/super_admin — que é o papel de todo destino que se pode cadastrar hoje —, junto do resto da observabilidade/custo.

Exemplo prático: os dois destinos de uma empresa

Quando uma análise conclui e dispara o evento, a Onvox AI despacha um POST para CADA destino ativo daquela empresa que aceite aquele gatilho, e cada um recebe uma versão do mesmo evento escopada pelo papel configurado naquele destino, não pelo papel de quem criou a análise.

O papel define o corpo, e só ele: dois destinos do mesmo papel recebem um corpo idêntico, byte a byte. O que muda entre eles é o endereço e a assinatura (cada destino tem o próprio segredo, então vazar o segredo de um não permite forjar entrega para o outro). Isso vale para quantos destinos existirem: o número de destinos afeta quantos POSTs saem, nunca o que cada um enxerga. Como os dois papéis cadastráveis (admin_company e super_admin) recebem o mesmo contrato, na prática todos os destinos de uma empresa recebem o mesmo corpo.

{
  "event": "analysis.completed",
  "analysisId": "an_9f8e7d6c",
  "role": "admin_company",
  "data": {
    "id": "an_9f8e7d6c",
    "status": "completed",
    "source": "upload",
    "displayScore": 87,
    "score": 87,
    "attributionStatus": "auto",
    "summary": "Cliente demonstrou interesse, mas pediu prazo para decidir.",
    "transcript": "...",
    "bant": { "budget": "Confirmado", "authority": null, "need": "Sim", "timing": "30 dias" },
    "audioUrl": "https://...",
    "tokensUsed": 4200,
    "cost": 0.42,
    "companyId": "comp_456",
    "salespersonId": "user_123",
    "salespersonName": "Helena Pereira",
    "jobId": "job_789"
  }
}

Análise vinda de coleta de integração (gatilho scheduled_collection, portanto papel administrador). Além do dossiê, o data traz os campos de telefonia — é por eles que você correlaciona a análise com a chamada no seu lado.

Exemplo abreviado: para destacar só os campos novos de integração, o JSON abaixo omite os campos de custo/observabilidade. O payload real de admin_company/super_admin também carrega score, attributionStatus, tokensUsed, cost, companyId, salespersonId e jobId, como na tabela Payload por papel:

{
  "event": "analysis.completed",
  "analysisId": "an_integracao",
  "role": "admin_company",
  "data": {
    "id": "an_integracao",
    "source": "onvox",
    "provider": "onvox",
    "externalCallId": "1784291064.69",
    "externalOwnerId": "1018",
    "onvox": {
      "call_id": "1784291064.69",
      "call_from_name": "Helena Pereira",
      "call_from_number": "1018",
      "call_to": "4532408500",
      "record_file": "20260717092426-1784291064.69-1018-4532408500-Outbound.wav"
    },
    "transcript": "..."
  }
}

Os identificadores, e para que serve cada um:

Verificar a assinatura (lado RECEPTOR)

Todo POST carrega três headers:

Content-Type: application/json
X-EvoluAI-Event: analysis.completed
X-EvoluAI-Timestamp: 1755600000
X-EvoluAI-Signature: sha256=8f1e2a9c...

A assinatura é HMAC-SHA256 do material "{timestamp}.{corpo_raw}", usando o segredo que você recebeu na criação do webhook. Some o timestamp na verificação para recusar replay de uma entrega antiga capturada por terceiros.

JavaScript (Node.js / Express)

const crypto = require('node:crypto');

function verifyOnvoxAiWebhook(secret, timestamp, rawBody, signatureHeader) {
  // rejeita timestamp com mais de 5 minutos (replay)
  const age = Math.abs(Date.now() / 1000 - Number(timestamp));
  if (age > 300) {
    throw new Error('Timestamp fora da janela, possível replay');
  }

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');

  const received = signatureHeader.replace(/^sha256=/, '');
  const a = Buffer.from(expected, 'hex');
  const b = Buffer.from(received, 'hex');

  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
    throw new Error('Assinatura inválida');
  }
}

// Express: use express.raw() nesta rota para ter o corpo CRU (não re-parseado)
app.post('/webhooks/onvox', express.raw({ type: 'application/json' }), (req, res) => {
  const rawBody = req.body.toString('utf8');
  verifyOnvoxAiWebhook(
    process.env.ONVOX_AI_WEBHOOK_SECRET,
    req.header('X-EvoluAI-Timestamp'),
    rawBody,
    req.header('X-EvoluAI-Signature')
  );

  const payload = JSON.parse(rawBody);
  // ... processa payload.data
  res.status(200).send('ok');
});

Python (Flask)

import hashlib
import hmac
import time

from flask import Flask, request, abort

app = Flask(__name__)
WEBHOOK_SECRET = "seu-segredo-aqui"

def verify_onvox_ai_webhook(secret, timestamp, raw_body, signature_header):
    if abs(time.time() - float(timestamp)) > 300:
        raise ValueError("Timestamp fora da janela, possível replay")

    expected = hmac.new(
        secret.encode("utf-8"),
        f"{timestamp}.{raw_body}".encode("utf-8"),
        hashlib.sha256,
    ).hexdigest()

    received = signature_header.removeprefix("sha256=")
    if not hmac.compare_digest(expected, received):
        raise ValueError("Assinatura inválida")

@app.post("/webhooks/onvox")
def receive_webhook():
    raw_body = request.get_data(as_text=True)
    try:
        verify_onvox_ai_webhook(
            WEBHOOK_SECRET,
            request.headers.get("X-EvoluAI-Timestamp"),
            raw_body,
            request.headers.get("X-EvoluAI-Signature"),
        )
    except ValueError:
        abort(401)

    payload = request.get_json()
    # ... processa payload["data"]
    return "ok", 200

Retry e backoff

Entregas falhas (qualquer resposta que não seja 2xx, inclusive 4xx, além de timeout e erro de rede) são reenfileiradas automaticamente com backoff exponencial, até 5 tentativas. Responda 2xx assim que tiver validado e enfileirado o processamento; não é preciso terminar todo o processamento síncrono dentro do handler.

Todas as 5 tentativas acontecem em menos de 2 minutos (backoff exponencial, base 5s), não sendo um retry espaçado ao longo de horas. Depois da 5ª falha, a entrega é descartada sem retry adicional; trate seu endpoint como best-effort e, se precisar de garantia forte, faça polling do dossiê pela API como reconciliação.

Gerenciar um webhook existente

Tudo pela mesma tela Configurações → Webhooks de Análise (admin_company/super_admin):

Limitações conhecidas (declaradas, não escondidas)

• Todo destino é de papel administrador: os papéis oferecidos no cadastro são admin_company e super_admin. Não há destino por vendedor nem por supervisor — ver Por que só papel de administrador. A quantidade é livre: vários destinos, inclusive no mesmo papel. Necessidade diferente disso é customização: fale com o nosso desenvolvimento.
• O escopo do destino é a EMPRESA, nunca uma pessoa: o papel reduz os campos do payload, não quais análises chegam. Um destino recebe todas as análises concluídas da empresa que casem com os gatilhos, e o filtro por pessoa é responsabilidade do seu fluxo.
• Sem evento de teste/ping: ver Callout acima. Planeje validar com uma análise real antes de ir pra produção.
• Sem histórico de entregas consultável pela empresa: a Onvox AI não expõe hoje uma tela ou endpoint com o histórico de tentativas/status de cada entrega (sucesso, falha, motivo). Se uma entrega falhar as 5 tentativas e for descartada, não há alerta automático nem registro visível no painel; a forma de perceber é notar que seu sistema não recebeu o evento esperado.
• DNS revalidado a cada tentativa, inclusive nos retries: proteção deliberada contra DNS rebinding (o destino é checado de novo antes de CADA tentativa de entrega, não só na criação do webhook). Efeito colateral: se o DNS do seu targetUrl passar a resolver pra um IP privado/loopback depois de configurado (ex.: infraestrutura interna reconfigurada), toda entrega, incluindo os 5 retries, falha silenciosamente na validação de segurança, sem alerta, até esgotar as tentativas e ser descartada. Mantenha o DNS do destino estável, ou reconfigure o webhook se o destino mudar de rede.

Próximos passos