Repetições, duplicatas e ordem nos webhooks do WhatsApp: como tratar
A Meta repete um webhook do WhatsApp que recebe qualquer resposta diferente de HTTP 200, imediatamente e depois com frequência decrescente por até 7 dias, e o descarta depois disso. As repetições vão para todos os apps inscritos na conta, por isso duplicatas são normais. Responda 200 rápido, deduplique pelo id da mensagem ou pelo id do status mais o próprio status, e ordene os eventos pelos timestamps deles.
O easyCoexistence conecta o número do seu app do WhatsApp Business à Cloud API da Meta pela Coexistência e absorve as reentregas da Meta antes que elas cheguem às suas automações, então uma mensagem repetida não recebe uma segunda resposta de IA.
Por quanto tempo a Meta continua repetindo um webhook que não recebeu HTTP 200, antes de descartá-lo.
Máximo de atualizações que a Meta agrupa em um único POST; a Meta não garante o agrupamento, então trate cada requisição de forma independente.
Maior payload que um POST de webhook do WhatsApp pode carregar.
Por quanto tempo o easyCoexistence guarda o id de cada mensagem recebida, para que uma mensagem reentregue não execute uma automação duas vezes.
Tentativas por encaminhamento para a sua Forward URL, cada uma esperando 10 segundos por um 2xx, ao longo de cerca de 33 horas.
Quando a Meta repete um webhook do WhatsApp?
Sempre que uma entrega ao seu endpoint recebe um status HTTP diferente de 200, ou nem chega a ser entregue. A Meta repete imediatamente, depois mais algumas vezes com frequência decrescente nos 7 dias seguintes, e descarta o que ainda não foi confirmado depois disso. As repetições vão para todos os apps inscritos na WhatsApp Business Account para aquele campo, e é por isso que a Meta avisa que elas podem gerar notificações duplicadas. Não existe API para buscar webhooks passados, então uma entrega que esgota os 7 dias fica perdida para o seu sistema.
Por que chegam duplicatas mesmo com o servidor funcionando bem?
Porque uma entrega pode dar certo do seu lado e ainda assim parecer falha para a Meta. Um handler que faz o trabalho antes de responder pode passar do tempo de espera da Meta, e a Meta repete algo que você já processou. Um deploy que reinicia o servidor no meio de uma requisição, um load balancer que retorna 502 por um instante ou um 201 ou 204 no lugar de 200 contam como falha. Os lotes acrescentam mais um caso: um único POST pode conter várias atualizações, então um timeout em um lote grande traz o lote inteiro de volta, incluindo as atualizações que você já tratou.
Qual chave usar para deduplicar?
Os ids da própria Meta, escolhidos por tipo de evento, porque uma mesma mensagem gera legitimamente vários webhooks. Uma chave de status sem o valor do status descartaria delivered e read como cópias de sent, e uma chave de chamada sem o evento manteria só a primeira etapa de uma chamada. Guarde as chaves com um índice único, para que dois workers tratando a mesma repetição não possam vencer os dois:
Em que ordem os webhooks chegam?
Não necessariamente na ordem em que as coisas aconteceram. A documentação da Meta não garante ordem nenhuma, uma entrega repetida chega depois das mais novas, e um status pode pular uma etapa: a Meta envia read sem delivered quando a mensagem é lida no instante em que chega. Por isso, guarde os eventos com o campo de timestamp de cada um, compare um status pela precedência e não pela chegada, e deixe uma mensagem mais recente do cliente prevalecer sobre uma anterior que chegou atrasada. Em um número com Coexistência, a importação única do histórico pode se sobrepor às mensagens em tempo real no período do onboarding, e o id da mensagem é o que concilia as duas.
Como é um handler seguro?
Quatro passos: verificar, responder exatamente 200, deduplicar e então processar a partir de uma fila, para que nada lento fique entre a requisição da Meta e a sua resposta. Esta versão verifica o X-Hub-Signature-256 com o app secret do seu próprio app da Meta; para um número conectado pelo easyCoexistence, a Meta assina com o app secret do easyCoexistence, então um destino direto se autentica com um secret longo no caminho da URL, ou passa a usar o encaminhamento gerenciado, assinado por número.
// meta-webhook.mjs: node meta-webhook.mjs (no dependencies)
import crypto from "node:crypto";
import http from "node:http";
const APP_SECRET = process.env.META_APP_SECRET; // the secret of the Meta app that subscribed
const seen = new Set(); // keys already accepted: a unique index in a database in production
// One key per thing that happened, so a redelivery maps to the same keys.
function keysOf(field, value) {
const keys = [];
for (const m of value.messages ?? []) keys.push(`${field}:msg:${m.id}`);
for (const s of value.statuses ?? []) keys.push(`${field}:status:${s.id}:${s.status}`);
for (const e of value.message_echoes ?? []) keys.push(`${field}:echo:${e.id}`);
for (const c of value.calls ?? []) keys.push(`${field}:call:${c.id}:${c.event}`);
return keys;
}
http.createServer((req, res) => {
const chunks = [];
req.on("data", (c) => chunks.push(c));
req.on("end", () => {
const raw = Buffer.concat(chunks);
const got = Buffer.from(String(req.headers["x-hub-signature-256"] ?? ""));
const want = Buffer.from("sha256=" + crypto.createHmac("sha256", APP_SECRET).update(raw).digest("hex"));
if (req.method !== "POST" || got.length !== want.length || !crypto.timingSafeEqual(got, want)) {
res.writeHead(401).end();
return;
}
res.writeHead(200).end(); // exactly 200, before any work
const body = JSON.parse(raw.toString("utf8"));
for (const entry of body.entry ?? []) {
for (const change of entry.changes ?? []) {
for (const key of keysOf(change.field, change.value ?? {})) {
if (seen.has(key)) continue; // a retry of something already accepted
seen.add(key);
// queue { key, field: change.field, value: change.value } for a worker here
console.log("new", key);
}
}
}
});
}).listen(process.env.PORT ?? 3000);Como o easyCoexistence trata as repetições em um número conectado?
Na entrada, o easyCoexistence verifica a assinatura da Meta, responde 200 e executa as automações depois da resposta, então a Meta não repete a entrega só porque uma resposta de IA levou alguns segundos. Cada id de mensagem recebida fica guardado por 7 dias, a duração da janela de repetição da Meta, e uma mensagem reentregue é reconhecida e não dispara uma segunda resposta automática.
Na saída para a sua Forward URL, cada alteração da Meta vira uma entrega com um id em X-EC-Delivery que se mantém o mesmo nas repetições do encaminhamento: 7 tentativas em cerca de 33 horas, cada uma esperando 10 segundos por um 2xx. Uma alteração que a própria Meta reentrega é encaminhada de novo com um novo id de entrega, então deduplique também pelos ids da Meta dentro de value.
Erros comuns
- Deduplicar status apenas pelo id. sent, delivered e read compartilham o mesmo wamid, então a chave precisa incluir o status.
- Processar antes de responder. Um handler lento faz a Meta repetir trabalho que você já fez; retorne 200 primeiro e processe a partir de uma fila.
- Retornar 201 ou 204. A documentação da Meta trata qualquer status diferente de 200 como falha na entrega e repete.
- Deduplicar encaminhamentos só pelo X-EC-Delivery. Uma alteração que a Meta reentrega chega com um novo id de entrega; mantenha os ids da Meta como segunda chave.
Os encaminhamentos para o seu servidor são assinados, enfileirados e repetidos, e cada número é monitorado 24/7. De R$ 29,90 a R$ 3,90 por número por mês, caindo conforme você adiciona números, com os 3 primeiros dias grátis.
O easyCoexistence é uma API e um servidor MCP multicanal que conecta agentes de IA, como o Claude e o ChatGPT, ao WhatsApp, Instagram, TikTok, Facebook e mais. No WhatsApp, ele usa o Coexistence: a empresa continua usando o número no app WhatsApp Business enquanto a IA trabalha pela API oficial da Meta.
Perguntas frequentes
Por quanto tempo devo guardar os ids que já recebi?
Pelo menos 7 dias, a janela de repetição da Meta. Uma entrega que a Meta repete no sexto dia ainda precisa bater com a sua chave, senão será processada como nova.
O que acontece com as mensagens dos meus clientes se o meu endpoint ficar fora do ar por dias?
A Meta repete por até 7 dias e depois descarta os webhooks. Em um número com Coexistência, as conversas continuam no app do WhatsApp Business no celular, então a empresa pode responder por lá.
Dá para recuperar webhooks que eu perdi?
Pela Meta, não: não existe API para dados históricos de webhooks. A importação única do histórico de um número com Coexistência acontece só no onboarding e não pode ser solicitada de novo para a mesma conexão.
A Meta envia a mesma atualização para mais de um servidor?
Ela envia para todos os apps inscritos na WhatsApp Business Account para aquele campo. Com um override de destino, os campos de mensagens do número vão para a URL do override em vez do callback padrão daquele app.
Continue lendo
Pronto para começar?
Configure o WhatsApp Coexistence em minutos, não em meses. O aplicativo continua funcionando no celular.
Começar teste grátisVerificado em