Webhooks de Alta Confiabilidade

Receba cada mensagem e status em tempo real. Sem expor a Meta.

A PliVant cuida de toda a recepção de eventos da Meta Cloud API, assina cada destino com HMAC-SHA256 e pode entregar o mesmo evento em até 10 endpoints por projeto — CRM, n8n, analytics ou seu backend.

Começar agora Documentação de Webhooks

Simulador de Eventos

Payloads normalizados e previsíveis

Esqueça a estrutura convoluta de 10 níveis da Meta. A PliVant entrega JSON limpo e pronto para o seu código.

{
  "id": "evt_01j8m4k9a1b2c3d4e5f6g7h8",
  "type": "messages.received",
  "version": "1",
  "occurred_at": "2026-09-21T05:40:20.000Z",
  "project_id": "9a1d7d94-1a3d-4d87-8a62-4df90f047a31",
  "phone_number_id": "89120f10-7f72-49a7-9875-89fe2c3ca901",
  "data": {
    "id": "wamid.HBgLNTUxMTk5OTk5ODg4OBUCABEYEkFDN0E4OTI...",
    "from": "5511999998888",
    "phone_number_id": "104928374829102",
    "type": "text",
    "text": {
      "body": "Olá! Gostaria de consultar o status do meu pedido #1049."
    },
    "timestamp": "1726785019"
  }
}

Header: X-PliVant-Signature: t=1726785020,v1=...HTTPS POST 200 OK

Segurança de Ponta

Assinatura HMAC-SHA256 e proteção contra Replay Attack

Cada webhook enviado pela PliVant contém o cabeçalho X-PliVant-Signature com um timestamp UNIX e o HMAC calculado com o segredo daquele endpoint. Seu servidor pode rejeitar qualquer requisição não assinada antes de processar.

Anti-SSRF com DNS Pinning: Proteção estrita contra chamadas para IPs internos ou metadados de nuvem.

Janela de Tolerância de 5 min: Previne ataques de repetição mesmo se o payload for interceptado.

Retentativas Automáticas: 5 tentativas com backoff exponencial se seu servidor oscilar.

const crypto = require('crypto');

function verifySignature(secret, rawBody, signatureHeader) {
  // signatureHeader: 't=1726785020,v1=abcdef123456...'
  const parts = Object.fromEntries(
    signatureHeader.split(',').map(item => item.split('='))
  );
  const timestamp = parts.t;
  const signature = parts.v1;

  if (!timestamp || !signature) return false;

  // Tolerância de 5 minutos contra replay attacks
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

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

  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

Contrato de Eventos

Garantia de Entrega e Tratamento de Falhas

Os webhooks seguem um contrato estrito. Cada evento possui um ID único para garantir idempotência e exige uma resposta rápida do seu servidor.

Eventos Principais

messages.received: Recebimento de mensagens do cliente (texto, áudio, foto, documento, botões).
messages.status: Status de envio da Meta (sent, delivered, read, failed) com metadata e tags do envio quando informados.
messages.echo: mensagem outbound feita pelo WhatsApp Business App quando a coexistência está ativa.
coexistence.history: chunks do histórico compartilhado no onboarding; são repassados ao seu sistema e nunca tratados como novas mensagens inbound.
coexistence.contacts: alterações de contatos do WhatsApp Business App; a PliVant apenas repassa o evento e não cria agenda ou CRM interno.
templates.status: revisão e disponibilidade do template: aprovação, rejeição, pausa e desativação.
templates.quality: mudança da qualidade Meta (GREEN, YELLOW, RED).
templates.category: recategorização e aviso prévio de mudança de categoria do template.
numbers.status: mudanças gerais de estado operacional do número.
numbers.quality: sinais de flag/unflag, upgrade/downgrade e limite atual do número.
numbers.name: aprovação ou rejeição do nome de exibição pela Meta.

Idempotência

Cada evento possui um id único (ex: evt_01j8m...). Seu sistema deve processar o mesmo ID apenas uma vez para evitar duplicações em retentativas.

SLA e Retentativas

Seu servidor deve responder com HTTP status 2xx (ex: 200 OK ou 204 No Content) em até 5 segundos.
Se houver timeout (mais de 5s) ou se o destino retornar 4xx ou 5xx, a fila reagenda a entrega.
Garantia de entrega e retentativas: até 5 tentativas com backoff exponencial.

Erros Comuns e Diagnóstico

Timeout: O endpoint da sua API está demorando muito para processar. Tente responder rápido e processar assincronamente.
401 / 403: Problema no cálculo da assinatura HMAC. Verifique a chave e a formatação do rawBody.
DNS / SSRF: O host de destino é inválido, interno ou inacessível. Utilize URLs públicas HTTPS.

Engenharia PliVant

Construído para não perder nenhuma mensagem

Filas com BullMQ & Redis

Processamento desacoplado de alta vazão. Mesmo com picos súbitos de mensagens, seu webhook é despachado ordenadamente.

Reenvio Manual no Painel

Seu servidor ficou fora do ar? Sem problemas. O painel lista todas as entregas com falha e permite reenvio com 1 clique.

Segredo HMAC Exclusivo

Chave HMAC gerada isoladamente por projeto. Você pode rotacionar a assinatura a qualquer momento no dashboard.

Métricas P95 & Taxa 2xx

Acompanhe a latência de resposta e a saúde do seu endpoint diretamente na tela de Webhooks do painel do cliente.

Filtro Granular de Eventos

Assine apenas o que interessa: mensagens, entrega/leitura, qualidade e categoria de templates ou saúde do número.

Compatível com tudo

Funciona perfeitamente com n8n, Typebot, Make, Chatwoot, Evolution, Next.js, Django, Laravel ou qualquer stack.

Integrações Imediatas

Conecte no seu ecossistema favorito em segundos

n8nTypebotMake (Integromat)ChatwootZapierNode.jsPythonPHP / LaravelGo

Criar conta e testar webhooks