Iniciar sessãoIniciar teste gratuito
Meta Tech Provider

Repetições, duplicados e ordem dos webhooks do WhatsApp: como os tratar

A Meta repete um webhook do WhatsApp que não receba HTTP 200, de imediato e depois com frequência decrescente durante até 7 dias, e descarta-o depois disso. As repetições vão para todas as aplicações subscritas à conta, por isso os duplicados são normais. Responda 200 rapidamente, deduplique pelo ID da mensagem ou pelo ID do estado mais o estado, e ordene os eventos pelas suas próprias marcas temporais.

A easyCoexistence liga o número da sua aplicação WhatsApp Business à Cloud API da Meta através da Coexistence e absorve as repetições da Meta antes de as suas automações as verem, para que uma mensagem repetida não receba uma segunda resposta de IA.

7 days

Durante quanto tempo a Meta repete um webhook que não recebeu HTTP 200, antes de o descartar.

1,000

A maioria das atualizações a Meta agrupa num único POST; a Meta não garante esse agrupamento, por isso trate cada pedido de forma independente.

3 MB

Maior payload que um POST de webhook do WhatsApp pode transportar.

7 days

Durante quanto tempo a easyCoexistence guarda cada ID de mensagem recebida, para que uma mensagem reenviada não execute uma automação duas vezes.

7 attempts

Tentativas por reencaminhamento para o seu URL de reencaminhamento, cada uma a aguardar 10 segundos por uma resposta 2xx, durante cerca de 33 horas.

Quando é que a Meta repete um webhook do WhatsApp?

Sempre que uma entrega para o seu endpoint recebe um código HTTP diferente de 200, ou não pode ser entregue de todo. A Meta repete de imediato e depois algumas vezes mais, com frequência decrescente, ao longo dos 7 dias seguintes, e descarta o que continuar sem confirmação depois disso. As repetições vão para todas as aplicações subscritas à conta WhatsApp Business para esse campo, por isso a Meta avisa que podem produzir notificações duplicadas. Não existe nenhuma API para obter webhooks passados, pelo que uma entrega que esgota os seus 7 dias fica perdida para o seu sistema.

Porque chegam duplicados mesmo quando o seu servidor está saudável?

Porque uma entrega pode ser bem-sucedida do seu lado e, mesmo assim, parecer falhada à Meta. Um handler que faz o trabalho antes de responder pode demorar mais do que a espera da Meta, e então a Meta repete algo que já processou. Uma implementação que reinicia o servidor a meio de um pedido, um balanceador de carga que devolve 502 durante um momento, ou um 201 ou 204 em vez de 200, contam todos como falhas. Os lotes acrescentam mais um caso: um único POST pode conter muitas atualizações, pelo que um tempo-limite num lote grande traz de volta o lote inteiro, incluindo as atualizações que já tratou.

Em que chave deve deduplicar?

Nos IDs da própria Meta, escolhidos por tipo de evento, porque uma mensagem produz legitimamente vários webhooks. Uma chave de estado sem o valor do estado descartaria delivered e read como cópias de sent, e uma chave de chamada sem o evento manteria apenas a primeira fase de uma chamada. Guarde as chaves com um índice único, para que dois processos que tratem a mesma repetição não possam ambos avançar:

messages[].idIncoming messages: the wamid.
statuses[].id + statusOne message has sent, delivered, read; each is its own event.
message_echoes[].idReplies the owner typed in the WhatsApp Business app.
calls[].id + eventA call's connect, statuses and terminate share the wacid.
user id + value + timestampuser_preferences: a customer can stop and resume more than once.

Em que ordem chegam os webhooks?

Não necessariamente pela ordem em que as coisas aconteceram. A documentação da Meta não garante qualquer ordem, uma entrega repetida chega depois das mais recentes, e um estado pode saltar um passo: a Meta envia read sem delivered quando uma mensagem é lida no momento em que chega. Por isso guarde os eventos com o seu próprio campo de marca temporal, compare um estado por ordem de precedência e não pela chegada, e deixe que uma mensagem posterior do cliente prevaleça sobre uma anterior que chegou atrasada. Num número em Coexistence, a importação única do histórico pode sobrepor-se às mensagens em tempo real durante a integração, e o ID da mensagem é o que as reconcilia.

Como é um handler seguro?

Quatro passos: verificar, responder exatamente 200, deduplicar e depois trabalhar a partir de uma fila, para que nada lento fique entre o pedido da Meta e a sua resposta. Esta versão verifica o X-Hub-Signature-256 com o segredo da sua própria aplicação Meta; para um número ligado através da easyCoexistence, a Meta assina com o segredo da aplicação da easyCoexistence, pelo que um destino direto autentica-se com um segredo longo no caminho do URL, ou passa a usar o reencaminhamento gerido e assinado por número.

meta-webhook.mjs: 200 first, then deduplicate (Node.js, no dependencies)
// 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 é que a easyCoexistence trata as repetições num número ligado?

À entrada, a easyCoexistence verifica a assinatura da Meta, responde 200 e executa as automações depois da resposta, para que a Meta não repita o pedido só porque uma resposta de IA demorou alguns segundos. Cada ID de mensagem recebida é guardado durante 7 dias, o tamanho da janela de repetição da Meta, e uma mensagem reenviada é reconhecida e não dispara uma segunda resposta automática.

À saída para o seu URL de reencaminhamento, cada alteração da Meta torna-se uma única entrega com um ID em X-EC-Delivery que se mantém igual nas repetições de reencaminhamento: 7 tentativas durante cerca de 33 horas, cada uma a aguardar 10 segundos por uma resposta 2xx. Uma alteração que a própria Meta volta a enviar é reencaminhada de novo com um novo ID de entrega, por isso deduplique também pelos IDs da Meta dentro de value.

Erros comuns

  • Deduplicar estados só pelo ID. sent, delivered e read partilham o wamid, por isso a chave precisa também do estado.
  • Processar antes de responder. Um handler lento faz a Meta repetir trabalho que já fez; devolva 200 primeiro e trabalhe a partir de uma fila.
  • Devolver 201 ou 204. A documentação da Meta trata qualquer estado diferente de 200 como entrega falhada e repete-a.
  • Deduplicar reencaminhamentos apenas pelo X-EC-Delivery. Uma alteração que a Meta volta a enviar chega com um novo ID de entrega; mantenha os IDs da Meta como segunda chave.
Fazer isto com a EasyCoexistence

Os reencaminhamentos para o seu servidor são assinados, colocados em fila e repetidos, e cada número é monitorizado 24 horas por dia, 7 dias por semana. De US$ 9 até US$ 0.75 por número por mês, descendo à medida que adiciona números, com os primeiros 3 dias grátis.

Perguntas frequentes

Durante quanto tempo devo guardar os IDs que já vi?

Pelo menos 7 dias, a janela de repetição da Meta. Uma entrega que a Meta repete no sexto dia tem de continuar a corresponder à sua chave, ou será processada como nova.

O que acontece às mensagens dos meus clientes se o meu endpoint ficar em baixo durante dias?

A Meta repete durante até 7 dias e depois descarta os webhooks. Num número em Coexistence, as conversas continuam na aplicação WhatsApp Business do telemóvel, para que a empresa possa responder a partir daí.

Posso reproduzir webhooks que perdi?

Não através da Meta: não existe nenhuma API para dados históricos de webhooks. A importação única do histórico de um número em Coexistence corre apenas na integração e não pode ser pedida de novo para a mesma ligação.

A Meta envia a mesma atualização para mais de um servidor?

Envia para todas as aplicações subscritas à conta WhatsApp Business para esse campo. Com uma substituição de destino, os campos de mensagens do número são enviados para o URL de substituição em vez do callback predefinido dessa aplicação.

Continue a ler

Pronto para começar?

Configure a Coexistência do WhatsApp em minutos, não em meses. A aplicação continua a funcionar no telemóvel.

Começar período experimental gratuito

Verificado em