Modo demo — dados fictícios
ContactoIA
Demo · Clínica Vitalis

Integrações

Ligue o atendimento a outros sistemas via webhooks ou API pública — exemplo. Webhooks e API exigem o plano Business.

Envie eventos do atendimento para Zapier, Make, n8n ou o seu próprio servidor. Cada pedido é assinado com HMAC-SHA256 no cabeçalho X-ContactoIA-Signature.

CRM da clínica

ativo
Mensagem recebida
Mensagem enviada
Contacto criado
Venda ganha
Oportunidade perdida

https://crm.clinicavitalis.example/webhooks/contactoia

Segredo de assinatura: …7f2a

Folha de satisfação

inativo
Inquérito de satisfação respondido

https://automacoes.clinicavitalis.example/csat

Segredo de assinatura: …c91e

Últimas entregas

Aceite pelo destino confirma apenas a resposta HTTP 2xx. Sem confirmação exige consultar os registos do destino antes de repetir a operação. Uma tentativa por evento, até 5 segundos, sem reenvio automático; histórico dos últimos 90 dias.

  • 20/11/2026, 14:22CRM da clínicamessage.sent
    Aceite pelo destino
    HTTP 200

    O destino respondeu com sucesso HTTP. Isto não comprova a conclusão do processamento no sistema externo.

  • 20/11/2026, 14:18CRM da clínicamessage.received
    Aceite pelo destino
    HTTP 200

    O destino respondeu com sucesso HTTP. Isto não comprova a conclusão do processamento no sistema externo.

  • 20/11/2026, 11:52CRM da clínicalead.won
    Aceite pelo destino
    HTTP 200

    O destino respondeu com sucesso HTTP. Isto não comprova a conclusão do processamento no sistema externo.

Documentação dos webhooks

Pedido enviado ao seu servidor

Cada evento é enviado por POST em JSON, com os cabeçalhos Content-Type: application/json, X-ContactoIA-Event e X-ContactoIA-Signature: sha256=<hex>. O cabeçalho User-Agent: ContactoIA-Webhooks/1.0 (+https://contactoia.lyntev.com/ajuda) identifica o remetente nos seus registos, mas não autentica o pedido: valide sempre a assinatura.

As integrações anteriores continuam a receber X-AtendeZap-Event e X-AtendeZap-Signature, com os mesmos valores dos novos nomes. Use os nomes ContactoIA nas novas integrações; não é necessário alterar um destinatário existente.

{
  "id": "1c9e…",
  "event": "message.received",
  "company_id": "…",
  "data": { "numero": "351912345678", "contato_nome": "Maria", "texto": "Olá", "tipo": "texto", "message_id": "<id da mensagem>" },
  "timestamp": "2026-10-27T10:00:00.000Z"
}

Eventos disponíveis:

  • message.received — Mensagem recebida. Mensagem do cliente recebida no WhatsApp e processada pela aplicação. tipo tem um dos valores técnicos texto, audio, imagem, video, documento, sticker (autocolante), localizacao, contacto ou outro (encomenda ou produto do catálogo, sondagem, convite para grupo ou evento). O evento é produzido na primeira tentativa de processamento e entregue numa única tentativa: algumas mensagens podem não gerar este evento. Para reconciliar, consulte GET /messages. data: { "numero": "351912345678", "contato_nome": "Maria", "texto": "Olá", "tipo": "texto", "message_id": "<id da mensagem>" }
  • message.sent — Mensagem enviada. Cada mensagem enviada pela aplicação e aceite pelo WhatsApp. origem: ia (resposta automática), humano (equipa na aplicação), api (API pública) ou sistema (confirmações e inquéritos). As respostas escritas diretamente no telemóvel não geram este evento. data: { "numero": "351912345678", "texto": "Olá! Em que posso ajudar?", "origem": "ia", "whatsapp_message_id": "<id do WhatsApp>" }
  • lead.created — Contacto criado. Contacto novo no CRM. origem: whatsapp (primeira mensagem recebida) ou manual (criado na aplicação). As importações em lote não geram eventos. data: { "numero": "351912345678", "nome": "Maria", "etapa": "Conversas", "origem": "whatsapp" }
  • lead.won — Venda ganha. O contacto passou para uma etapa do tipo Ganho. origem: utilizador (equipa no CRM) ou ia (etapa indicada pela IA a partir da conversa). confirmado: true quando a equipa definiu ou confirmou a etapa; false quando a IA a indicou e ainda não foi confirmada, por isso não deve ser tratada como venda concluída. Quando a equipa confirma uma etapa indicada pela IA, o evento é enviado de novo, com outro id, origem utilizador e confirmado: true: trate-o como a confirmação do anterior com o mesmo numero e etapa, para não contar a mesma venda duas vezes. valor é o valor registado no contacto, em euros. data: { "numero": "351912345678", "nome": "Maria", "etapa": "Ganho", "valor": 180, "origem": "utilizador", "confirmado": true }
  • lead.lost — Oportunidade perdida. O contacto passou para uma etapa do tipo Perda. Mesmos campos de lead.won; a confirmação pela equipa de uma Perda indicada pela IA também volta a enviar o evento, com confirmado: true. data: { "numero": "351912345678", "nome": "Maria", "etapa": "Perda", "valor": 0, "origem": "ia", "confirmado": false }
  • csat.responded — Inquérito de satisfação respondido. O cliente respondeu ao inquérito de satisfação. nota de 1 a 5; comentario pode ser null. data: { "numero": "351912345678", "contato_nome": "Maria", "nota": 5, "comentario": "Muito bom" }
Verificar a assinatura

A assinatura é o HMAC-SHA256, em hexadecimal, do corpo exato recebido (antes de o converter de JSON), com o segredo de assinatura do webhook. Compare em tempo constante. Depois de validar, rejeite pedidos com timestamp demasiado antigo (por exemplo, mais de 5 minutos) e ignore um id já processado.

Os exemplos preferem a assinatura ContactoIA e só usam o nome anterior quando o novo está ausente. Se ambos estiverem presentes e discordarem, rejeitam o pedido. Uma assinatura nova vazia ou inválida nunca deve recorrer à antiga. Confirme também que os cabeçalhos de evento presentes coincidem entre si e com event no corpo já validado.

Node.js

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

function verify(rawBody, currentHeader, legacyHeader, secret) {
  if (currentHeader != null && legacyHeader != null
      && currentHeader !== legacyHeader) return false;
  const signatureHeader = currentHeader ?? legacyHeader;
  if (typeof signatureHeader !== "string"
      || !/^sha256=[0-9a-f]{64}$/.test(signatureHeader)) return false;
  const expected = "sha256=" + crypto.createHmac("sha256", secret)
    .update(rawBody).digest("hex");
  const a = Buffer.from(expected), b = Buffer.from(signatureHeader);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}
// Valide os bytes originais antes de interpretar o JSON.
// verify(rawBody, headers.get("X-ContactoIA-Signature"),
//   headers.get("X-AtendeZap-Signature"), secret);

PHP

function verify(
    string $rawBody, ?string $currentHeader,
    ?string $legacyHeader, string $secret
): bool {
    if ($currentHeader !== null && $legacyHeader !== null
        && $currentHeader !== $legacyHeader) return false;
    $signatureHeader = $currentHeader ?? $legacyHeader;
    if ($signatureHeader === null
        || !preg_match('/^sha256=[0-9a-f]{64}$/D', $signatureHeader)) return false;
    $expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);
    return hash_equals($expected, $signatureHeader);
}
// $rawBody = file_get_contents('php://input');
// verify($rawBody, $_SERVER['HTTP_X_CONTACTOIA_SIGNATURE'] ?? null,
//   $_SERVER['HTTP_X_ATENDEZAP_SIGNATURE'] ?? null, $secret);

Python

import hashlib, hmac

def verify(raw_body: bytes, current_header, legacy_header, secret: str) -> bool:
    if (current_header is not None and legacy_header is not None
            and current_header != legacy_header):
        return False
    signature_header = (current_header if current_header is not None
                        else legacy_header)
    if not isinstance(signature_header, str) or not signature_header.isascii():
        return False
    expected = "sha256=" + hmac.new(
        secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header)

# Use os bytes originais, sem voltar a codificar o JSON.
# verify(raw_body, headers.get("X-ContactoIA-Signature"),
#     headers.get("X-AtendeZap-Signature"), secret)
Entrega
  • Só endereços HTTPS públicos na porta 443; redirecionamentos não são seguidos.
  • Uma única tentativa por evento, com limite de 5 segundos; não há reenvios automáticos.
  • Cada empresa pode ter até 10 webhooks ativos. Os destinos recebem o evento por ordem, alguns de cada vez, por isso um destino lento pode atrasar a entrega aos seguintes.
  • Uma resposta 2xx aparece como «Aceite pelo destino»: confirma a aceitação HTTP, sem comprovar a conclusão da operação no sistema externo.
  • Outro código ou ausência de resposta aparece como «Sem confirmação». O destino pode ter recebido ou processado o evento; consulte os seus registos antes de decidir repetir a operação.
  • «Últimas entregas» mostra as 50 tentativas mais recentes dos últimos 90 dias, com o código HTTP quando disponível.
  • Ao renovar o segredo, as entregas seguintes passam a usar o novo segredo de imediato.

Demonstração — dados fictícios, apenas leitura.