Recebendo mensagens com webhooks de entrada

O que são webhooks de entrada

Os webhooks de mensagens de entrada permitem que a Zapini avise o seu sistema, em tempo real, sempre que uma nova mensagem chega à sua instância de WhatsApp. Em vez de você ficar consultando a API repetidamente, é a Zapini que faz uma requisição POST para a URL que você cadastrar.

Passo 1 — Criar um endpoint público

Crie um endpoint HTTPS no seu servidor que aceite requisições POST com corpo JSON. Ele deve responder rapidamente com HTTP 200 para confirmar o recebimento. Faça o processamento pesado de forma assíncrona, para não atrasar a resposta.

💡 Dica: sempre use HTTPS no endpoint do webhook e valide a origem da requisição antes de confiar no conteúdo.

Passo 2 — Cadastrar a URL do webhook

Informe a URL do seu endpoint na configuração da instância. A partir daí, cada mensagem recebida gera uma chamada ao seu webhook.

Passo 3 — Tratar o payload

O corpo enviado ao seu endpoint inclui dados da mensagem recebida, como remetente, conteúdo e identificadores. Um exemplo simplificado:

{
  "event": "message.received",
  "instance_id": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "from": "+5511999999999",
    "sender_name": "Maria",
    "type": "text",
    "message": "Olá, gostaria de mais informações",
    "received_at": "2026-06-13T10:30:00Z"
  }
}

No seu servidor, leia o JSON, registre a mensagem e dispare a lógica que precisar (abrir um ticket, atualizar um CRM, acionar a API para responder, etc.).

Passo 4 — Testar e validar

Envie uma mensagem real para o número da instância e confirme que seu endpoint recebeu a chamada. Verifique os logs do seu servidor e garanta que está respondendo HTTP 200.

Boas práticas

1. Responda rápido (200) e processe em segundo plano.
2. Trate o recebimento de forma idempotente, usando o identificador da mensagem para evitar duplicidades.
3. Implemente novas tentativas e monitore falhas no seu endpoint.
4. Para enviar respostas automáticas, combine o webhook com o endpoint de envio de mensagens da API.