Skip to main content

O que são Webhooks?

Webhooks permitem que você receba notificações em tempo real quando eventos acontecem na sua instância WhatsApp. Em vez de fazer polling constante na API, o EnviaAI envia os dados diretamente para seu servidor.
Webhooks funcionam como “callbacks HTTP” - quando algo acontece, enviamos um POST para sua URL.

Tipos de Webhook

O EnviaAI oferece dois tipos de webhooks:

Outbound (Receber Eventos)

Você configura uma URL e recebe eventos do EnviaAI.
Seu Servidor ← EnviaAI
Eventos disponíveis:
  • Mensagens recebidas
  • Status de entrega
  • Conexão/desconexão

Inbound (Enviar Mensagens)

O EnviaAI gera uma URL única para você enviar mensagens.
Seu Servidor → EnviaAI
Ideal para:
  • Zapier, Make, n8n
  • Integrações no-code
  • Chamadas HTTP simples

Eventos Disponíveis

Mensagens

EventoDescrição
message.receivedNova mensagem recebida
message.sentMensagem enviada com sucesso
message.deliveredMensagem entregue ao destinatário
message.readDestinatário leu a mensagem
message.failedFalha no envio

Instância

EventoDescrição
instance.connectedInstância conectou ao WhatsApp
instance.disconnectedInstância desconectou
instance.qr_updatedNovo QR Code gerado

Estrutura do Payload

Todos os webhooks seguem esta estrutura:
{
  "event": "message.received",
  "timestamp": "2026-02-03T12:00:00.000Z",
  "data": {
    // Dados específicos do evento
  }
}

Exemplo: Mensagem Recebida

{
  "event": "message.received",
  "timestamp": "2026-02-03T12:00:00.000Z",
  "data": {
    "messageId": "msg_abc123",
    "instanceId": "inst_xyz789",
    "chatId": "chat_def456",
    "from": "5511999999999",
    "type": "text",
    "content": "Olá!",
    "contactName": "João Silva",
    "isGroup": false
  }
}

Verificação de Assinatura

Todos os webhooks incluem uma assinatura para verificação:
X-EnviaAI-Signature: sha256=abc123...
Verificação em Node.js:
const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}
Sempre verifique a assinatura antes de processar webhooks em produção.

Política de Retry

Se seu endpoint falhar, tentamos novamente:
TentativaDelay
1Imediato
230 segundos
32 minutos
410 minutos
51 hora
66 horas
Após 6 tentativas, o evento é marcado como falho.

Requisitos do Endpoint

Seu endpoint de webhook deve:
1

Aceitar POST

Receber requisições HTTP POST
2

Responder rápido

Retornar 2xx em até 5 segundos
3

Ser público

Estar acessível via HTTPS na internet
4

Processar async

Processar eventos em background após responder

Boas Práticas

Responda rápido

Retorne 200 OK imediatamente e processe em background

Seja idempotente

Use messageId para evitar processar duplicatas

Verifique assinatura

Sempre valide a assinatura em produção

Log tudo

Registre todos os eventos para debugging

Próximos Passos