EntrarComeçar teste grátis
easyCoexistence APIs oficiais

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.

subscribe

O valor que hub.mode sempre traz na requisição de verificação da Meta; hub.challenge é um inteiro a ser devolvido.

sha256=

Prefixo de X-Hub-Signature-256, seguido da assinatura SHA256 que a Meta gera a partir do payload e do App Secret.

5 seconds

Com que rapidez um endpoint de webhook do Messenger deve responder a cada notificação com 200 OK.

1 hour

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.

36 hours

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_challenge e hub_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:

Python: hub.challenge and X-Hub-Signature-256
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", 200

O 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_destination ou 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:

Node.js: checking X-EC-Signature on a forwarded event
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.
Fazendo isso com o EasyCoexistence

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