Verificação do webhook do Facebook: hub.challenge e X-Hub-Signature-256
O Facebook verifica um endpoint de webhook com um GET que traz hub.mode definido como subscribe, hub.verify_token e hub.challenge; o endpoint compara o token com o do painel da app e devolve o valor de hub.challenge no corpo. Cada evento chega depois como um POST assinado em X-Hub-Signature-256: sha256= seguido do HMAC-SHA256 do payload, cuja chave é o App Secret da app.
A easyCoexistence trata do lado da Meta para cada Página que liga: a app da easyCoexistence responde ao hub.challenge, verifica o X-Hub-Signature-256 e subscreve a Página a feed, mensagens e menções, depois reencaminha os eventos para o seu endpoint HTTPS assinados com X-EC-Signature e com um segredo próprio dessa Página.
O valor que o hub.mode traz sempre no pedido de verificação da Meta; hub.challenge é um inteiro a devolver.
Prefixo de X-Hub-Signature-256, seguido da assinatura SHA256 que a Meta gera a partir do payload e do App Secret.
A rapidez com que um endpoint de webhook do Messenger deve responder a cada notificação com 200 OK.
De entregas falhadas antes de um alerta de Webhooks desativados e do cancelamento da subscrição da app à Página.
Durante quanto tempo a Meta repete uma notificação de Página falhada, com frequência decrescente, antes de a descartar.
O que contém o pedido de verificação da Meta?
Um GET para o URL de callback, enviado sempre que o produto Webhooks é configurado no painel da app ou quando é criada uma subscrição através de /{app-id}/subscriptions. Traz três parâmetros de consulta:
- hub.mode: é sempre subscribe.
- hub.challenge: um inteiro que o endpoint tem de devolver.
- hub.
verify_token: a cadeia de caracteres introduzida no campo Verify Token do painel. - O PHP substitui os pontos por sublinhados, pelo que os lê como
hub_mode,hub_challengeehub_verify_token.
Como deve o endpoint responder?
Com um 200 cujo corpo inteiro é o valor de hub.challenge, mas apenas quando hub.mode é subscribe e hub.verify_token coincide; qualquer outra situação recebe um 403, como na aplicação de exemplo da Meta. O painel indica se o endpoint passou, e /{app-id}/subscriptions responde com sucesso ou com um erro. O endpoint precisa de HTTPS com um certificado TLS ou SSL válido, uma vez que os certificados autoassinados não são suportados.
Como se calcula o X-Hub-Signature-256?
Como um HMAC-SHA256 do payload do pedido, com chave no App Secret da app, escrito em hexadecimal minúsculo após sha256=. O guia do Messenger da Meta acrescenta que a assinatura abrange o payload com o Unicode com escape, pelo que uma cadeia como äöå conta como \u00e4\u00f6\u00e5: calcule o hash do corpo bruto exatamente como foi recebido, nunca de uma cópia descodificada ou serializada de novo. A Meta diz que validar é opcional, mas recomenda-o vivamente.
Como se verifica no código?
Guarde os bytes brutos, calcule o HMAC, compare em tempo constante e só depois faça a análise. O get_data do Flask devolve o corpo sem alterações, que é aquilo sobre o qual a assinatura foi calculada; analisar primeiro e serializar de novo alteraria os bytes. Um pequeno endpoint que responde à verificação e valida 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 espera a Meta depois da verificação?
Um 200 OK por cada notificação, no prazo de 5 segundos para eventos do Messenger. A Meta agrupa até 1.000 atualizações por entrega, sem o garantir, 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 por fim descartadas.
- Notificações do Messenger: repetidas algumas vezes de imediato; após 15 minutos de falhas, um alerta chega à conta de programador.
- Após uma hora de falhas, segue-se um alerta de Webhooks desativados e a app deixa de estar subscrita à Página até voltar a subscrever.
- As novas tentativas podem entregar um evento duas vezes e fora de ordem, por isso elimine os duplicados e ordene as mensagens pelo carimbo temporal.
- As notificações passadas não podem ser consultadas depois, por isso guarde o que precisa à medida que chega.
Como é que a easyCoexistence cumpre as verificações da Meta?
A app da easyCoexistence na Meta tem um único URL de callback para as Páginas que liga, e esse endpoint faz ele próprio as duas verificações. Responde ao GET apenas quando hub.mode é subscribe e o token de verificação coincide, comparado em tempo constante, e devolve 403 nos outros casos; lê cada POST como texto bruto, recalcula o X-Hub-Signature-256 com o segredo da app, recusa uma divergência com 401 e responde de imediato à Meta, tratando o evento depois de responder.
Como é que a easyCoexistence assina o que reencaminha?
Com uma assinatura própria, já que o cabeçalho da Meta só pode ser verificado com o segredo da app da easyCoexistence e não é reencaminhado. Cada entrada de uma Página ligada com um endpoint definido é enviada por POST para lá como JSON, {platform, account_id, external_id, entry}, com um cabeçalho X-EC-Signature no formato t=<unix>,v1=<hex>, em que v1 é o HMAC-SHA256 do carimbo temporal, de um ponto e do corpo bruto, com chave no segredo de assinatura dessa Página:
- O segredo começa por whsec_ e é mostrado uma só vez, através de
set_social_webhook_destinationou PUT /channels/:id/webhook na API de Parceiros. - Definir de novo o URL emite um novo segredo, e um URL nulo desliga o reencaminhamento.
- Cada reencaminhamento é enviado uma única vez, com uma espera máxima de 8 segundos, sem seguir redirecionamentos, para um endereço HTTPS que resolve para um IP público.
- Não é guardada nenhuma cópia do evento, pelo que não há nada a partir do qual repetir.
Como se verifica o X-EC-Signature?
Separe o cabeçalho em t e v1, rejeite um carimbo temporal 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. Em 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 tem de ser o próprio valor de hub.challenge.
- Calcular o HMAC depois de um analisador JSON. Analisar e serializar de novo altera os bytes, e a Meta assina o payload com Unicode com escape, por isso calcule o hash do corpo bruto.
- Fazer o trabalho antes de responder. O Messenger espera um 200 em 5 segundos, e uma hora de falhas cancela a subscrição da app à Página.
- Verificar a assinatura da Meta nos eventos reencaminhados. A Meta assina com o segredo da app da easyCoexistence; um evento reencaminhado traz X-EC-Signature, verificado com o segredo de assinatura da Página.
De US$ 9 a US$ 0,75 por ligação por mês, com descida à medida que acrescenta ligações, e os primeiros 3 dias grátis.
Perguntas frequentes
De onde vem o token de verificação?
Pode escolhê-lo livremente. É a cadeia de caracteres introduzida no campo Verify Token ao configurar os webhooks no painel da app, ou o verify_token enviado para /{app-id}/subscriptions.
Posso testar a verificação com curl?
Sim. O guia do Messenger da Meta envia um GET com hub.verify_token, hub.challenge=CHALLENGE_ACCEPTED e hub.mode=subscribe, e um endpoint em funcionamento responde CHALLENGE_ACCEPTED.
O que acontece se o meu endpoint falhar durante uma hora?
A Meta envia um alerta de Webhooks desativados e cancela a subscrição da app à Página. Depois de corrigir o endpoint, volte a subscrever a Página através de subscribed_apps.
Preciso de uma app própria da Meta para receber os webhooks de uma Página?
Não com a easyCoexistence. A Meta entrega à app da easyCoexistence, que reencaminha os eventos de cada Página para o endpoint que definir, assinados com X-EC-Signature.
Continue a ler
Ligue o seu primeiro canal em dois minutos.
Sem revisões de plataformas para esperar. Ligue o WhatsApp, o Instagram, o TikTok ou outro canal, peça depois à sua IA que publique, responda ou faça um relatório, e veja-a trabalhar.
- 3 dias grátis
- Cancele quando quiser
- Só APIs oficiais
- Monitorizado 24/7
Verificado em