Como receber as mensagens do WhatsApp e os comentários de redes sociais dos seus clientes por webhook
Cada conexão recebe seu próprio webhook para as mensagens do WhatsApp ou os comentários de redes sociais dos seus clientes, pela Partner API da easyCoexistence. As mensagens do WhatsApp vão da Meta direto para essa URL, assinadas com o segredo do app Tech Provider, e não com um segredo que você possui; por isso, um segredo longo e aleatório no caminho da URL as autentica. Comentários e DMs do Instagram e do Facebook, e comentários do TikTok, são encaminhados assim que chegam, assinados por conta com X-EC-Signature.
Tamanho máximo, segundo a Meta, da URL de callback alternativa que envia as mensagens de um número para o seu endpoint.
Por quanto tempo a Meta repete um webhook do WhatsApp que o seu endpoint não aceitou, com frequência decrescente, o que pode gerar duplicatas.
A rede da Meta; consultas whois de rota para ela listam os endereços de onde partem os webhooks do WhatsApp, que a Meta muda periodicamente.
O tamanho máximo de um payload de webhook do WhatsApp, segundo a Meta.
Idade máxima do timestamp assinado de um evento encaminhado; passado esse prazo, o evento deve ser rejeitado, com o HMAC comparado em tempo constante.
Como cada conexão recebe o próprio destino?
Por meio de uma chamada por recurso. Um número do WhatsApp usa PUT /connections/{id}/webhook com url e verify_token, ou o mesmo par como webhook_url e webhook_verify_token na sua sessão de conexão, para que o número seja roteado para você desde o primeiro minuto. Uma conta de rede social usa PUT /channels/{id}/webhook depois de conectada. Enviar url como null em qualquer um dos dois desativa a entrega. Os dois caminhos diferem em quem entrega e em como você autentica:
| WhatsApp number | Instagram, Facebook, TikTok | |
|---|---|---|
| Set with | webhook_url on the session, or PUT /connections/{id}/webhook | PUT /channels/{id}/webhook, after it connects |
| Delivered by | Meta, straight to your URL | easyCoexistence, forwarding each event as it arrives |
| Body | Meta's webhook, unchanged | platform, account_id, external_id and the network's entry |
| Authenticate | A long random secret in the URL path | X-EC-Signature, keyed with the account's secret |
| Retries | Meta's own, for up to 7 days | None: one attempt |
| Copy kept | None | None |
Como apontar as mensagens de um número para o seu endpoint?
Informe uma URL HTTPS cujo caminho contenha um segredo longo e aleatório, além de um token de verificação: webhook_verify_token numa sessão de conexão, de 8 a 200 caracteres, ou verify_token no PUT. A Meta verifica a URL de imediato com um GET contendo hub.mode=subscribe, hub.verify_token e hub.challenge, e o seu endpoint deve responder com o valor de hub.challenge quando o token coincidir. Se esse handshake falhar, o PUT retorna 502 meta_rejected com a mensagem da própria Meta; numa sessão de conexão, o número ainda se conecta, e o last_error da sessão informa por que a URL não foi aplicada.
import express from "express";
import { timingSafeEqual } from "node:crypto";
const PATH_SECRET = process.env.WA_PATH_SECRET; // the random part of webhook_url
const VERIFY_TOKEN = process.env.WA_VERIFY_TOKEN; // the verify token you sent
const app = express();
function same(a, b) {
const x = Buffer.from(String(a)), y = Buffer.from(String(b));
return x.length === y.length && timingSafeEqual(x, y);
}
// Meta's handshake, run when the destination is set
app.get("/wa/:secret", (req, res) => {
if (!same(req.params.secret, PATH_SECRET)) return res.sendStatus(404);
if (req.query["hub.mode"] !== "subscribe" || !same(req.query["hub.verify_token"], VERIFY_TOKEN)) {
return res.sendStatus(403);
}
res.send(req.query["hub.challenge"]);
});
// Messages, echoes and the one-time import; payloads reach 3 MB
app.post("/wa/:secret", express.json({ limit: "4mb" }), (req, res) => {
if (!same(req.params.secret, PATH_SECRET)) return res.sendStatus(404);
res.sendStatus(200); // answer first: Meta retries for up to 7 days
enqueue(req.body); // deduplicate on each message id before acting
});Por que não é possível verificar a assinatura da Meta, e o que a substitui?
A Meta assina cada entrega com X-Hub-Signature-256, um HMAC-SHA256 do payload gerado com o App Secret do app receptor. Para os números dos seus clientes, esse app é o app Tech Provider da easyCoexistence, cujo segredo nunca é compartilhado, então o cabeçalho não pode ser verificado do seu lado. A credencial é o segredo longo e aleatório no caminho da URL: compare-o em tempo constante e recuse qualquer outra coisa. Como segunda camada, coloque na lista de permissão as rotas registradas para o AS32934 da Meta e atualize essa lista, já que a Meta muda seus endereços IP periodicamente.
Quais webhooks do WhatsApp chegam à sua URL?
Os campos que uma URL de callback alternativa da Meta pode carregar: messages, para o que os clientes enviam e o status do que você envia; smb_message_echoes, para o que a empresa envia pelo app do WhatsApp Business; e o histórico da importação única, além de smb_app_state_sync. A Meta nunca envia webhooks de template, nem webhooks de conta como account_update, para uma substituição. Eles chegam ao callback da easyCoexistence, por isso a revisão de templates é lida por polling e uma rejeição chega até você como evento de status.
- O destino é definido na conta do WhatsApp Business, então dois números de uma mesma conta o compartilham: faça o roteamento por value.metadata.
phone_number_id. - A mídia chega como ID; busque o arquivo na Meta com o token do cliente, obtido na chamada de credenciais.
- Os payloads podem chegar a 3 MB, então aumente qualquer limite de tamanho do corpo definido abaixo disso.
Como é um evento social encaminhado?
Um POST com Content-Type application/json e um cabeçalho X-EC-Signature, com quatro chaves: platform; account_id, o ID do canal que a Partner API usa; external_id, o ID da conta na rede; e entry. Para Instagram e Facebook, entry é o entry de webhook da Meta sem alterações, com changes para comentários e menções e messaging para DMs. Para o TikTok, ele traz o evento comment.update com o conteúdo interpretado, e comment_id, video_id e parent_comment_id como strings, para que IDs de 64 bits não sejam arredondados.
- Contas do Instagram são inscritas em comentários, mensagens e menções; Páginas do Facebook em feed, messages e mention; o TikTok envia comment.update.
- A easyCoexistence não recebe eventos de comentários do YouTube nem do LinkedIn: o PUT deles responde 400
not_supported, e os comentários são lidos pela API de cada rede com as credenciais. - Os encaminhamentos não trazem cabeçalho X-EC-Event nem X-EC-Delivery, então deduplique pelos IDs da própria rede, como um ID de comentário ou um mid de mensagem.
{
"platform": "instagram",
"account_id": "<CHANNEL_ID>",
"external_id": "<INSTAGRAM_ACCOUNT_ID>",
"entry": {
"id": "<INSTAGRAM_ACCOUNT_ID>",
"time": 1793440800,
"changes": [
{
"field": "comments",
"value": {
"id": "<COMMENT_ID>",
"from": { "id": "<INSTAGRAM_SCOPED_ID>", "username": "<USERNAME>" },
"text": "<COMMENT_TEXT>",
"media": { "id": "<MEDIA_ID>", "media_product_type": "<MEDIA_PRODUCT_TYPE>" }
}
}
]
}
}Como verificar o X-EC-Signature, passo a passo?
Com o signing_secret que PUT /channels/{id}/webhook retornou, exibido apenas uma vez e exclusivo daquela conta. O cabeçalho tem o formato t=<unix>,v1=<hex>. Então, para cada entrega:
- Leia o corpo bruto da requisição como bytes, antes de qualquer parsing de JSON.
- Separe o cabeçalho por vírgulas em t, um horário Unix em segundos, e v1, um hash hexadecimal.
- Rejeite a entrega se t estiver a mais de 5 minutos do seu relógio.
- Calcule o HMAC-SHA256 sobre t, um ponto e o corpo bruto, com a chave secreta daquela conta, em hexadecimal.
- Compare com v1 em tempo constante, depois responda 2xx e enfileire o trabalho.
import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";
const app = express();
const secrets = new Map(); // channel id -> signing_secret, kept in your database
app.post("/hooks/social", express.raw({ type: "application/json" }), (req, res) => {
const sig = Object.fromEntries(
(req.get("X-EC-Signature") ?? "").split(",").map((part) => part.split("=", 2)),
);
if (!/^\d+$/.test(sig.t ?? "") || Math.abs(Date.now() / 1000 - Number(sig.t)) > 300) {
return res.sendStatus(401); // missing or stale timestamp
}
let event;
try {
event = JSON.parse(req.body.toString("utf8")); // platform, account_id, external_id, entry
} catch {
return res.sendStatus(400);
}
const secret = secrets.get(event.account_id);
if (!secret || !sig.v1) return res.sendStatus(401);
const expected = createHmac("sha256", secret)
.update(sig.t + ".")
.update(req.body) // the raw bytes, exactly as they arrived
.digest("hex");
if (expected.length !== sig.v1.length ||
!timingSafeEqual(Buffer.from(expected), Buffer.from(sig.v1))) {
return res.sendStatus(401);
}
res.sendStatus(204); // one attempt and no retries: acknowledge, then work
enqueue(event);
});O que acontece quando nenhum destino está definido?
Nada chega até você, e nada fica aguardando para ser enviado depois. Um número sem webhook_url recorre ao callback da easyCoexistence, onde as suas mensagens são descartadas sem serem armazenadas, e ele não recebe importação de histórico de chat, que só é solicitada quando existe um destino. Uma conta de rede social sem destino não é encaminhada: seus eventos ainda chegam ao app da easyCoexistence, mas nenhum fica retido para você. Defina cada destino antes de precisar do tráfego.
O que acontece com um destino quando uma conexão cai ou é removida?
Um número mantém o seu destino registrado. Quando um número desconectado se reconecta, a easyCoexistence define a sua URL novamente com a Meta, e o mesmo acontece quando um número suspenso volta. Remover uma conta de rede social apaga o destino e o segredo dela, então, após a reconexão, chame PUT /channels/{id}/webhook de novo e armazene o novo segredo. Esse PUT emite um novo segredo sempre que é chamado com uma URL, e o antigo deixa de assinar imediatamente.
Como configurar
- Put a secret in the URLChoose an HTTPS URL whose path holds a long random string, 200 characters or fewer in all, and make its GET answer Meta's hub.challenge.
- Route the number's messagesSend webhook_url and webhook_verify_token on the connect session, or PUT /connections/{id}/webhook once the number is connected.
- Turn on each social accountCall PUT /channels/{id}/webhook with your URL and store the signing_secret it returns against that channel.
- Verify, then acknowledgeCheck the path secret on WhatsApp deliveries and X-EC-Signature on forwarded ones, answer 2xx at once, then process from a queue.
Erros comuns
- Verificar o X-Hub-Signature-256 nas entregas do WhatsApp dos seus clientes. A Meta o calcula com o App Secret da easyCoexistence, que nunca é compartilhado, então a verificação nunca passa; autentique com o segredo no caminho da URL.
- Verificar o X-EC-Signature sobre o JSON já parseado. O HMAC cobre o corpo bruto byte a byte, e serializar de novo altera os bytes, então verifique antes do parsing.
- Usar um só segredo para todos os canais. Cada conta de rede social assina com o próprio segredo, e os eventos de status com outro, então busque o segredo pelo account_id.
- Fazer trabalho lento antes de responder a um evento encaminhado. Ele é enviado uma vez, aguarda 8 segundos pela sua resposta e nunca é repetido, então responda 2xx primeiro e processe depois.
A easyCoexistence direciona as mensagens de cada número de cliente da Meta direto para o seu servidor, e encaminha comentários e DMs do Instagram e do Facebook, e comentários do TikTok, para o seu endpoint assim que chegam, assinados por conta, sem manter cópia e com cada conexão monitorada 24/7. De US$ 9 a US$ 0.75 por conexão por mês, com o valor caindo conforme você adiciona conexões, e os primeiros 3 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
Posso verificar a assinatura da Meta nas mensagens do WhatsApp dos meus clientes?
Não. A Meta as assina com o segredo do app Tech Provider da easyCoexistence, que nunca é compartilhado. Autentique com o segredo longo e aleatório no caminho da sua URL e, opcionalmente, com os intervalos de IP da Meta.
As conexões do YouTube e do LinkedIn encaminham eventos de comentários?
Não. A easyCoexistence não recebe eventos de comentários de nenhum dos dois, então PUT /channels/{id}/webhook responde 400 not_supported. Leia os comentários deles pela API de cada rede com as credenciais do canal.
Os eventos sociais encaminhados são repetidos se o meu servidor estiver fora do ar?
Não. Cada um é enviado uma vez e nenhuma cópia é mantida. As entregas do WhatsApp são diferentes, porque a própria Meta as repete por até 7 dias.
As mensagens passam pela easyCoexistence?
No WhatsApp, não: a Meta entrega as mensagens de um número direto ao webhook que você definiu. Comentários e DMs das redes sociais são encaminhados ao seu endpoint assim que chegam, assinados por conta, sem manter cópia.
Continue lendo
Conecte seu primeiro canal em dois minutos.
Sem esperar aprovação das plataformas. Conecte o WhatsApp, o Instagram, o TikTok ou outro canal, peça para a sua IA publicar, responder ou trazer os números, e veja funcionando.
- 3 dias grátis
- Cancele quando quiser
- Só APIs oficiais
- Monitorado 24/7
Verificado em