Iniciar sessãoIniciar teste gratuito
easyCoexistence APIs oficiais

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.

subscribe

O valor que o hub.mode traz sempre no pedido de verificação da Meta; hub.challenge é um inteiro a devolver.

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

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

1 hour

De entregas falhadas antes de um alerta de Webhooks desativados e do cancelamento da subscrição da app à Página.

36 hours

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

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

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 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.
Fazer isto com a EasyCoexistence

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