BLOG

Webhook ou SSE WhatsApp: qual usar na sua integração

Webhook ou SSE WhatsApp: veja quando usar cada um, com critérios de decisão, retentativas, assinatura e chaves por número. Leia e escolha certo.

Ilustração de um celular com WhatsApp do qual saem duas rotas luminosas: uma leva a um servidor com engrenagens e fila de

Webhook ou SSE no WhatsApp? A regra é simples: use webhook assinado quando o destino é outro servidor, como ERP, CRM, fila ou n8n, e SSE quando o destino é uma tela aberta, como um chat ao vivo. Muitas integrações usam os dois. Neste guia você vê como cada um funciona, os critérios de decisão e como separar chaves de API por número.

Principais pontos

  • Webhook é push de servidor para servidor, sem estado; SSE é uma conexão aberta de servidor para cliente, com estado.
  • Webhook tem novas tentativas quando o seu endpoint falha; no SSE, o cliente precisa reconectar e retomar de onde parou.
  • Webhook pede validação de assinatura, resposta rápida e tratamento de eventos repetidos (idempotência).
  • SSE autentica no início da conexão e serve para interfaces ao vivo, sem polling constante.
  • Chaves de API por organização, área ou número limitam o estrago se uma credencial vazar e facilitam a depuração.
  • O padrão mais comum é combinar: webhook para o backend, SSE para a tela.

Webhook ou SSE no WhatsApp: a resposta curta

A escolha cabe em uma pergunta: quem recebe o evento? Se for outro servidor (seu ERP, seu CRM, uma fila ou um fluxo no n8n), use webhook. Se for uma tela aberta no navegador de um atendente, use SSE (server-sent events).

Os dois entregam o mesmo tipo de informação: mensagem recebida, mudança de status de uma mensagem enviada (na fila, enviada, entregue, lida), alteração em uma conversa. O que muda é o caminho e o que acontece quando algo dá errado.

Quando cada um é a escolha certa

  • Webhook assinado: o evento chega por requisição POST no endereço do seu sistema. Serve para gravar no CRM, abrir um chamado, atualizar um pedido ou acionar uma automação. Não precisa de ninguém olhando uma tela.
  • SSE: o navegador abre uma conexão e fica ouvindo. Serve para a tela do atendente mostrar a mensagem nova e o status na hora, sem recarregar a página.
  • Os dois juntos: o webhook cuida do que precisa ser gravado e processado; o SSE cuida do que precisa ser visto agora.

A própria Meta descreve o webhook como o mecanismo para receber notificações de mensagens e status no seu servidor, conforme a visão geral de webhooks do WhatsApp.

E o polling? Por que perde para os dois

Quem pesquisa webhook ou polling quer saber se vale perguntar ao servidor de tempos em tempos: chegou algo novo? Funciona em um protótipo, mas desperdiça requisições e atrasa o evento até a próxima consulta. Se você consulta a cada 30 segundos, a mensagem pode esperar quase isso para aparecer. Webhook e SSE invertem a lógica: quem tem a novidade avisa.

O FlowZap oferece os dois caminhos na mesma conta. Os detalhes técnicos estão em /docs.

Webhook assinado com novas tentativas: como funciona

O webhook é o caminho clássico para integrar o WhatsApp com um sistema próprio. Você informa uma URL, e cada evento chega nela como uma requisição HTTP.

Push de servidor para servidor

O fluxo é direto: aconteceu algo no número, o provedor monta um JSON e envia por POST ao seu endpoint. O seu sistema responde com um código 2xx para confirmar o recebimento. Como cada requisição é independente, o endpoint não guarda conexão aberta. Isso combina bem com funções serverless e com servidores que sobem e descem conforme a demanda.

Assinatura: como saber que o evento é de verdade

Seu endpoint é uma URL pública, então qualquer pessoa pode tentar enviar um JSON forjado para ela. A assinatura resolve isso. No WhatsApp Cloud API, a Meta envia o cabeçalho X-Hub-Signature-256, calculado com HMAC-SHA256 sobre o corpo bruto da requisição, usando o segredo do aplicativo. A documentação da Meta sobre como criar o endpoint detalha o procedimento.

Três cuidados práticos:

  • Calcule a assinatura sobre o corpo bruto, antes de interpretar o JSON. Se você reserializar o objeto, o resultado pode mudar.
  • Compare em tempo constante (em Node.js, crypto.timingSafeEqual), para não vazar informação pelo tempo de resposta.
  • Descarte sem processar o que não bater com a assinatura.

Esses detalhes são da Meta. No FlowZap, os webhooks também são assinados; o formato exato da assinatura está em /docs.

Novas tentativas quando o seu sistema cai

Sistemas ficam fora do ar: deploy, banco lento, pico de tráfego. No WhatsApp Cloud API, se o endpoint não responde com 2xx, a Meta tenta de novo com intervalos crescentes, por até 24 horas, segundo guia sobre as funções e boas práticas dos webhooks do WhatsApp. Conferir o valor atual na documentação oficial é sempre uma boa ideia.

O lado ruim: o mesmo evento pode chegar duas vezes. Por isso, quem consome webhook precisa tratar repetição. Veremos como na seção de boas práticas. Os webhooks do FlowZap também têm novas tentativas, e a política completa fica em /docs.

Eventos em tempo real (SSE): quando a tela precisa ver na hora

Webhook entrega para servidores. Mas e a tela do atendente? Ela roda no navegador, que não tem URL pública para receber POST. É aí que entram os eventos em tempo real.

O que é server-sent events

SSE é uma conexão HTTP que fica aberta, na qual o servidor envia eventos em texto (Content-Type: text/event-stream) sempre que algo acontece. O fluxo é unidirecional: do servidor para o cliente. Diferente do WebSocket, ele não precisa de protocolo próprio; roda sobre HTTP. A explicação do bunny.net sobre SSE mostra o funcionamento básico.

A API original da Meta não expõe um stream SSE. Plataformas como o FlowZap recebem os eventos e os repassam por esse canal, que é o que fornecemos como eventos em tempo real.

Reconexão e retomada de onde parou

Conexões caem: o atendente troca de Wi-Fi, o notebook dorme. O SSE tem reconexão nativa no navegador, e o cabeçalho Last-Event-ID permite ao cliente dizer qual foi o último evento recebido para retomar dali. Na prática, a garantia de entrega depende de o cliente reconectar e retomar. Se ele ficou muito tempo fora, vale recarregar o estado da conversa pela API REST ao voltar.

Onde o SSE brilha: chat ao vivo e painéis

  • Tela de atendimento que mostra a mensagem nova do cliente sem recarregar.
  • Indicador de status da mensagem enviada mudando de enviada para entregue e lida.
  • Painel da supervisão com a fila de conversas se atualizando.

O limite honesto: conexão aberta é estado. Cada atendente conectado ocupa um socket no servidor, e quem constrói a própria camada precisa pensar em balanceamento de carga e em como distribuir eventos entre instâncias. Usando o SSE pronto de uma plataforma, essa parte fica com ela.

Critérios de decisão: tabela comparativa

Compare os dois lado a lado antes de escolher.

Critério Webhook assinado SSE
Direção do fluxo Servidor para servidor Servidor para cliente (navegador ou app), em um só sentido
Garantia de entrega Maior: novas tentativas automáticas se o endpoint falhar Moderada: depende de o cliente reconectar e retomar
Estado Sem estado, bom para serverless Conexão aberta, exige gerenciar sockets
Segurança Assinatura do corpo (HMAC-SHA256 no caso da Meta) Credencial (chave ou token) na abertura da conexão
Caso de uso n8n, CRM, ERP, filas, bots Chat ao vivo, painel de atendentes, alertas visuais

Direção, garantia de entrega e estado

O webhook é a escolha quando perder evento custa caro: uma confirmação de pagamento, um lead novo, um status de entrega que atualiza um pedido. A repetição de tentativas protege você de quedas curtas. O SSE é a escolha quando o evento só importa enquanto alguém está olhando. Se a tela estava fechada, o dado continua salvo no sistema e será carregado quando ela abrir.

Segurança: assinatura x credencial na conexão

No webhook, quem recebe precisa provar que o remetente é legítimo, por isso a assinatura. No SSE, quem abre a conexão é o seu cliente, então a autenticação acontece no início, com uma chave ou token. Os dois modelos são válidos; o erro é tratar um como o outro.

Cinco perguntas para decidir

  1. Quem recebe? Um servidor, webhook. Uma tela, SSE.
  2. Posso perder um evento? Se não, webhook, com fila e controle de repetidos.
  3. Tem alguém olhando a tela agora? Se sim e a latência importa, SSE.
  4. Minha infraestrutura aguenta conexões abertas? Se roda em serverless, comece pelo webhook.
  5. Preciso reprocessar eventos? Webhook com fila facilita; no SSE, recarregue pelo estado da API.

A comparação segue as descrições da Meta para o webhook e da explicação sobre SSE do bunny.net.

Chaves de API por organização, área ou número

Escolher o canal de eventos é metade da decisão. A outra metade é quem pode usar a API. No FlowZap, a API REST aceita chaves em três níveis: organização, área e número.

Quando usar cada nível

  • Organização: a integração central, que enxerga tudo. Boa para o sistema principal da empresa, como o ERP que conversa com todas as áreas.
  • Área: isola um fluxo de trabalho. Boa quando uma equipe ou um cliente atendido (no caso de agências) precisa de acesso próprio, sem ver o resto.
  • Número: limita a chave a um único número de WhatsApp. Boa para depurar um canal específico ou para dar acesso restrito a um parceiro ou a um sistema externo.

Quanto menor o alcance da chave, menor o estrago se ela vazar em um repositório, em um print ou na conta de um fornecedor.

Exemplo: cobrança separada do suporte

Imagine uma empresa com vendas, suporte e financeiro, cada um com sua área e seu número:

  • O sistema de cobrança usa uma chave da área do financeiro e recebe só os eventos dela. O time de suporte nunca passa por esse fluxo.
  • A ferramenta de chat do suporte abre o SSE com uma chave da área de suporte.
  • O CRM central, que cadastra todo mundo, usa uma chave da organização.
  • Uma consultoria que ajuda a depurar o número de vendas recebe uma chave daquele número, e só dele.

A lista de operações da API e a forma de criar cada chave estão em /docs. Para entender por que uma API própria faz diferença no dia a dia da operação, leia vantagens de usar uma API como o FlowZap no WhatsApp.

Boas práticas para webhooks e SSE funcionarem sem dor de cabeça

A maior parte dos problemas em integrações com WhatsApp se resume a três: demora para responder, evento repetido e conexão que cai sem ninguém perceber.

Responda primeiro, processe depois

Responda 2xx assim que validar a assinatura e guardar o evento. Só depois faça o trabalho pesado (consulta lenta, chamada a um modelo de IA, gravação em vários sistemas), de preferência em uma fila. Se o endpoint demora, o provedor entende como falha e reenvia. Guias de integração apontam um limite de espera de cerca de 5 segundos; confirme o valor atual na documentação da Meta.

É a técnica de confirmar primeiro e processar depois. Ela evita duplicidade em automações longas. O passo a passo prático está em webhook do WhatsApp no n8n.

Idempotência: o mesmo evento pode chegar duas vezes

Como as novas tentativas existem justamente para não perder evento, repetição é esperada. Trate assim:

  • Guarde o ID do evento ou da mensagem que você já processou.
  • Ao receber de novo, ignore e responda 2xx.
  • Escreva ações de forma que repeti-las não cause estrago: atualizar um status é seguro; criar um pedido a cada recebimento, não.

Imagine um aviso de pagamento que chega duas vezes. Sem controle, o cliente recebe dois recibos. Com o ID guardado, o segundo é descartado.

Reconexão no SSE e fila de processamento

No SSE, parta do princípio de que a conexão vai cair. Faça a tela reconectar sozinha, envie o último ID recebido e, se o intervalo foi grande, recarregue as conversas pela API REST. Para o backend, o desenho mais estável é: webhook recebe, valida, coloca na fila; trabalhadores processam; a tela se atualiza via SSE.

Se a dúvida é custo, o texto API do WhatsApp é paga? O que muda em outubro de 2026 ajuda a planejar o volume de mensagens.

Segurança e LGPD na hora de receber eventos

Cada evento de WhatsApp carrega dados pessoais: nome, telefone, o conteúdo da conversa. Receber isso em um endpoint exige cuidado, sem alarmismo e sem improviso.

Menos acesso, menos risco

A LGPD (Lei 13.709/2018, arts. 46 a 49) pede medidas técnicas para proteger dados pessoais. Na integração, isso se traduz em dar a cada sistema só o acesso de que precisa. Uma chave restrita a uma área ou a um número reduz o alcance de um vazamento: quem pegar a chave da cobrança não lê as conversas do suporte.

Assinatura e credenciais como medida de segurança

Validar a assinatura do webhook evita aceitar requisições forjadas. Guardar chaves em variáveis de ambiente e trocá-las quando alguém sai da equipe também conta. No SSE, mantenha a chave fora do código que roda no navegador sempre que possível.

Se, mesmo com os cuidados, houver um incidente de segurança com dados pessoais, o regulamento da ANPD de 2024 prevê comunicação à autoridade e aos titulares afetados em até 3 dias úteis a contar do conhecimento do evento, de acordo com o regulamento de comunicação de incidente e com a explicação da Confidata. Os casos e prazos têm nuances, então valide o procedimento com o jurídico da sua empresa. Este texto não é aconselhamento jurídico.

Um lembrete que vale para qualquer integração: enviar mensagens só é correto para quem autorizou. Veja o checklist de consentimento da LGPD para WhatsApp Business.

Como o FlowZap oferece os dois

O FlowZap reúne, na mesma conta, os recursos que este guia comparou.

Webhooks assinados, SSE, chaves e integrações

  • API REST com chaves por organização, por área ou por número.
  • Webhooks assinados com novas tentativas, para alimentar CRM, ERP, filas e automações.
  • Eventos em tempo real (SSE), para telas e painéis que precisam ver mensagens e status na hora.
  • Chatwoot, exemplos para n8n e Make, e o conector MCP para usar a conta no Claude e no ChatGPT, do plano Growth em diante (veja em /claude-chatgpt).

Todos os planos incluem API e webhooks. Os valores e limites de cada plano estão em /precos; como referência, o Start custa R$ 49 por mês e o Growth, R$ 149 por mês. O cadastro não pede cartão, o pagamento é por Pix ou cartão de crédito e não há fidelidade.

Combinar webhook e SSE: um desenho que funciona

Uma empresa de serviços recebe pedidos pelo WhatsApp. O desenho fica assim:

  1. Chega uma mensagem do cliente. O webhook entrega o evento ao sistema da empresa, que valida a assinatura, responde 2xx e grava o contato e o pedido no CRM.
  2. A mesma mensagem aparece, via SSE, na tela do atendente que está de plantão, sem recarregar.
  3. O atendente responde. O status da mensagem muda de na fila para enviada, entregue e lida, e a tela acompanha ao vivo.
  4. Se o sistema da empresa ficar fora do ar por alguns minutos, as novas tentativas do webhook evitam que o pedido se perca.

Próximos passos

Para ver o que mais a plataforma cobre, como caixa de conversas em equipe, CRM e respostas automáticas, consulte /produto. Se a sua operação tem vários atendentes, o guia de WhatsApp para empresas multiusuário mostra como organizar as equipes. Na dúvida entre webhook ou SSE no WhatsApp, volte às cinco perguntas da tabela: quem recebe, se pode perder evento e se há alguém olhando a tela.

Comece com o FlowZap

Veja o que o FlowZap faz e compare os planos. Para criar a conta, basta o nome da empresa, um e-mail e uma senha: o cadastro não pede cartão de crédito, e o pagamento é por Pix ou cartão de crédito, sem fidelidade.

Perguntas frequentes

Qual a diferença entre webhook e SSE no WhatsApp?

O webhook envia cada evento por POST de servidor para servidor, com novas tentativas se o seu sistema falhar. O SSE mantém uma conexão aberta e entrega eventos ao vivo ao navegador. Use webhook para ERP, CRM e filas, e SSE para telas de atendimento.

Webhook ou polling: qual é melhor para integrar o WhatsApp?

Na maioria dos casos, webhook. No polling você consulta o servidor repetidamente, gasta requisições e o evento espera até a próxima consulta. No webhook, o aviso chega assim que o evento acontece. O polling só serve como apoio para conferir o estado depois de uma queda.

O que são novas tentativas de webhook?

São reenvios automáticos do evento quando o seu endpoint não responde com sucesso (código 2xx). No WhatsApp Cloud API, a Meta reenvia com intervalos crescentes por até 24 horas. Por isso o seu sistema deve ignorar eventos repetidos, guardando o ID do que já processou.

Como validar um webhook assinado do WhatsApp?

Calcule o HMAC-SHA256 do corpo bruto da requisição com o segredo configurado e compare com o cabeçalho de assinatura, em tempo constante. No WhatsApp Cloud API, o cabeçalho é X-Hub-Signature-256. Só interprete o JSON depois de validar. Para o FlowZap, veja o formato em /docs.

Posso usar chaves de API diferentes por número de WhatsApp?

Sim. No FlowZap, a API REST aceita chaves por organização, por área ou por número. Assim cada sistema acessa só o que precisa, e um vazamento de chave atinge menos conversas. Isso também facilita a depuração de um canal específico.

Fontes

  1. facebook.com
  2. facebook.com
  3. hookdeck.com
  4. bunny.net
  5. lgpd.ms.gov.br
  6. confidata.com.br

Atenda o WhatsApp da empresa em equipe.

Conecte o número por QR code e responda pelo navegador, com a API para integrar seus sistemas.

Cadastro sem cartão de crédito · Pix ou cartão de crédito, sem fidelidade