Verificação de webhook do Facebook: hub.challenge e X-Hub-Signature-256
O Facebook verifica um endpoint de webhook com um GET que traz hub.mode igual a subscribe, hub.verify_token e hub.challenge; o endpoint compara o token com o definido no App Dashboard e devolve o challenge como corpo. Depois, cada evento chega como POST assinado em X-Hub-Signature-256: sha256= seguido do HMAC-SHA256 do payload, usando o app secret como chave.
O easyCoexistence cuida do lado da Meta para cada Página que você conecta: o app dele responde ao hub.challenge, verifica o X-Hub-Signature-256 e inscreve a Página em feed, mensagens e menções, depois encaminha os eventos para o seu endpoint HTTPS assinados com X-EC-Signature e com um segredo próprio daquela Página.
O valor que hub.mode sempre traz na requisição de verificação da Meta; hub.challenge é um inteiro a ser devolvido.
Prefixo de X-Hub-Signature-256, seguido da assinatura SHA256 que a Meta gera a partir do payload e do App Secret.
Com que rapidez um endpoint de webhook do Messenger deve responder a cada notificação com 200 OK.
Do número de entregas com falha antes de um alerta de Webhooks Disabled e da cancelação da inscrição do app na Página.
Por quanto tempo a Meta repete uma notificação de Página com falha, com frequência decrescente, antes de descartá-la.
O que a requisição de verificação da Meta contém?
Um GET para a URL de callback, enviado sempre que o produto Webhooks é configurado no App Dashboard ou uma inscrição é criada por /{app-id}/subscriptions. Vêm com ele três parâmetros de query:
- hub.mode: sempre subscribe.
- hub.challenge: um inteiro que o endpoint precisa devolver.
- hub.
verify_token: a string digitada no campo Verify Token do App Dashboard. - O PHP troca os pontos por underlines, então os lê como
hub_mode,hub_challengeehub_verify_token.
Como o endpoint deve responder?
Com um 200 cujo corpo inteiro é o valor de hub.challenge, mas somente quando hub.mode for subscribe e hub.verify_token coincidir; qualquer outra coisa recebe um 403, como no app de exemplo da Meta. O App Dashboard informa se o endpoint passou, e /{app-id}/subscriptions responde com sucesso ou erro. O endpoint precisa de HTTPS com certificado TLS ou SSL válido, já que certificados autoassinados não são suportados.
Como o X-Hub-Signature-256 é calculado?
Como um HMAC-SHA256 do payload da requisição, com chave igual ao App Secret do app, escrito em hexadecimal minúsculo após sha256=. O guia do Messenger da Meta acrescenta que a assinatura cobre o payload com Unicode escapado, então uma string como äöå conta como \u00e4\u00f6\u00e5: faça o hash do corpo bruto exatamente como recebido, nunca de uma cópia decodificada ou serializada novamente. A Meta diz que validar é opcional, mas recomenda fortemente.
Como você verifica isso no código?
Guarde os bytes brutos, calcule o HMAC, compare em tempo constante e só então faça o parse. O get_data do Flask devolve o corpo intocado, que é sobre o que a assinatura foi calculada; fazer o parse primeiro e serializar de novo mudaria os bytes. Um endpoint pequeno que responde à verificação e checa cada POST:
import hashlib, hmac, os
from flask import Flask, abort, request
app = Flask(__name__)
VERIFY_TOKEN = os.environ["VERIFY_TOKEN"]
APP_SECRET = os.environ["APP_SECRET"].encode()
@app.get("/webhooks/facebook")
def verify():
token = request.args.get("hub.verify_token", "")
if request.args.get("hub.mode") == "subscribe" and hmac.compare_digest(token.encode(), VERIFY_TOKEN.encode()):
return request.args.get("hub.challenge", ""), 200
abort(403)
@app.post("/webhooks/facebook")
def receive():
raw = request.get_data() # the bytes Meta signed
expected = "sha256=" + hmac.new(APP_SECRET, raw, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected.encode(), request.headers.get("X-Hub-Signature-256", "").encode()):
abort(401)
# answer at once; hand request.get_json() to a queue for the work
return "EVENT_RECEIVED", 200O que a Meta espera depois da verificação?
Um 200 OK para cada notificação, em até 5 segundos para eventos do Messenger. A Meta agrupa até 1.000 atualizações por entrega, sem garantir isso, e trata as falhas assim:
- Notificações de Página: repetidas de imediato, depois mais algumas vezes com frequência decrescente ao longo de 36 horas, e então descartadas.
- Notificações do Messenger: repetidas algumas vezes de imediato; após 15 minutos de falhas, um alerta chega à conta de desenvolvedor.
- Após uma hora de falhas, segue um alerta de Webhooks Disabled e o app deixa de ser inscrito na Página até se inscrever novamente.
- As repetições podem entregar um evento duas vezes e fora de ordem; então deduplique e ordene as mensagens pelo timestamp.
- Notificações passadas não podem ser consultadas depois; por isso, armazene o que precisar à medida que chegar.
Como o easyCoexistence passa nas verificações da Meta?
O app da Meta do easyCoexistence tem uma única URL de callback para as Páginas que ele conecta, e esse endpoint faz as duas verificações por conta própria. Ele responde ao GET somente quando hub.mode é subscribe e o verify token coincide, comparado em tempo constante, e devolve 403 caso contrário; lê cada POST como texto bruto, recalcula o X-Hub-Signature-256 com seu app secret, recusa uma divergência com 401 e responde à Meta de imediato, processando o evento após a resposta.
Como o easyCoexistence assina o que encaminha?
Com uma assinatura própria, já que o cabeçalho da Meta só pode ser verificado com o app secret do easyCoexistence e não é repassado. Cada entrada de uma Página conectada com endpoint definido é enviada por POST para ele como JSON, {platform, account_id, external_id, entry}, com um cabeçalho X-EC-Signature no formato t=<unix>,v1=<hex>, onde v1 é o HMAC-SHA256 do timestamp, de um ponto e do corpo bruto, usando o segredo de assinatura daquela Página:
- O segredo começa com whsec_ e é exibido uma única vez, por
set_social_webhook_destinationou PUT /channels/:id/webhook na Partner API. - Definir a URL novamente gera um novo segredo, e uma URL nula desliga o encaminhamento.
- Cada encaminhamento é enviado uma vez, aguardando até 8 segundos, sem seguir redirecionamentos, para um endereço HTTPS que resolve para um IP público.
- Nenhuma cópia do evento é guardada, então não há nada para repetir.
Como você verifica o X-EC-Signature?
Divida o cabeçalho em t e v1, rejeite um timestamp com mais de 5 minutos, recalcule o HMAC sobre t, um ponto e o corpo bruto com o segredo de assinatura da Página, e compare em tempo constante. No Node.js, com o corpo guardado como bytes brutos:
import crypto from "node:crypto";
import express from "express";
const app = express();
const SECRET = process.env.EC_SIGNING_SECRET; // whsec_..., shown once
app.post("/events/facebook", express.raw({ type: "application/json" }), (req, res) => {
const sig = Object.fromEntries(
String(req.get("X-EC-Signature") ?? "").split(",").map((part) => part.split("="))
);
const fresh = Math.abs(Date.now() / 1000 - Number(sig.t)) <= 300;
const expected = crypto
.createHmac("sha256", SECRET)
.update(Buffer.concat([Buffer.from(`${sig.t}.`), req.body]))
.digest("hex");
const ok = fresh && typeof sig.v1 === "string" && sig.v1.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig.v1));
if (!ok) return res.sendStatus(401);
res.sendStatus(200); // answer first: forwards are not retried
const { platform, account_id, external_id, entry } = JSON.parse(req.body.toString("utf8"));
// queue entry for the work
});Erros comuns
- Envolver hub.challenge em JSON ou aspas. O corpo do 200 precisa ser o próprio valor do challenge.
- Calcular o HMAC depois de um parser JSON. Fazer o parse e serializar de novo muda os bytes, e a Meta assina o payload com Unicode escapado; então faça o hash do corpo bruto.
- Fazer o trabalho antes de responder. O Messenger espera um 200 em até 5 segundos, e uma hora de falhas desinscreve o app da Página.
- Checar a assinatura da Meta em eventos encaminhados. A Meta assina com o app secret do easyCoexistence; um evento encaminhado traz X-EC-Signature, verificado com o segredo de assinatura da Página.
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
De onde vem o verify token?
Você escolhe. É a string digitada no campo Verify Token ao configurar os webhooks no App Dashboard, ou o verify_token enviado para /{app-id}/subscriptions.
Dá para testar a verificação com curl?
Dá. O guia do Messenger da Meta envia um GET com hub.verify_token, hub.challenge=CHALLENGE_ACCEPTED e hub.mode=subscribe, e um endpoint funcionando responde CHALLENGE_ACCEPTED.
O que acontece se meu endpoint falhar por uma hora?
A Meta envia um alerta de Webhooks Disabled e desinscreve o app da Página. Depois de corrigir o endpoint, inscreva a Página de novo por meio de subscribed_apps.
Preciso de um app da Meta próprio para receber os webhooks de uma Página?
Não com o easyCoexistence. A Meta entrega ao app dele, que encaminha os eventos de cada Página para o endpoint que você definiu, assinados com X-EC-Signature.
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