Iniciar sessãoIniciar teste gratuito
easyCoexistence APIs oficiais

Verificação de webhooks do Instagram: hub.challenge e X-Hub-Signature-256

Configurar webhooks do Instagram exige um endpoint HTTPS que responda ao GET de verificação da Meta, que traz hub.mode definido como subscribe, hub.verify_token e hub.challenge, comparando o token e devolvendo o challenge. Depois, a Meta envia eventos POST em JSON assinados em X-Hub-Signature-256 com o segredo da app, assim que esta subscreve os campos e cada conta é subscrita através do edge subscribed_apps.

A easyCoexistence trata do lado da Meta: a sua app passa a verificação, verifica o X-Hub-Signature-256, subscreve cada conta do Instagram ligada a comments, messages e mentions, e reencaminha os eventos para o seu endpoint HTTPS, assinados com X-EC-Signature e um segredo por conta, vigiando cada ligação em permanência.

subscribe

O valor hub.mode está sempre presente no pedido de verificação da Meta.

36 hours

Período durante o qual a Meta volta a tentar uma notificação falhada, com frequência decrescente, antes de a descartar.

15 minutes

De entregas de mensagens com falha antes de a Meta enviar um alerta para a conta de programador.

1 hour

De entregas de mensagens com falha antes de um alerta Webhooks Disabled e do cancelamento da subscrição da app na conta.

Live

Modo da app que a Meta exige antes de a app receber notificações das contas dos seus utilizadores.

Como funciona a configuração dos webhooks do Instagram?

Em quatro passos, pela ordem indicada no guia da Meta. O endpoint tem de passar a verificação antes de se poder selecionar qualquer campo, a app tem de estar Live para receber notificações das contas dos seus utilizadores, e a verificação da empresa é obrigatória para o acesso de produção.

1EndpointAn HTTPS URL with a valid certificate answers the verification GET
2App fieldsCallback URL, verify token and fields set in the App Dashboard
3Each accountPOST /<IG_ID>/subscribed_apps turns its notifications on
4TestA dashboard test, then a real event, reach the endpoint

O que contém o pedido de verificação?

Um GET para a URL de callback, enviado sempre que o produto Webhooks é configurado no painel da app. Quando hub.verify_token coincide com o token do próprio endpoint, a resposta é um 200 com o valor de hub.challenge como corpo completo; caso contrário, um 403. O painel indica se o endpoint passou.

  • hub.mode: sempre subscribe.
  • hub.challenge: um inteiro gerado pela Meta, que o endpoint tem de devolver.
  • hub.verify_token: a cadeia introduzida no campo Verify Token do painel, que só a Meta e o endpoint devem conhecer.
  • Em PHP, os pontos nestes nomes passam a sublinhados, pelo que os valores chegam como hub_mode, hub_challenge e hub_verify_token.
The verification request and its answer
GET https://<YOUR_HOST>/webhooks/instagram
  ?hub.mode=subscribe
  &hub.challenge=1158201444
  &hub.verify_token=<YOUR_VERIFY_TOKEN>

HTTP/1.1 200 OK
Content-Type: text/plain

1158201444

Onde se definem o callback e os campos?

No painel da app, em Instagram, API setup with Instagram login, Configure webhooks: a URL de callback e o verify token ficam aí, e ao guardar dispara-se o pedido de verificação. O produto Instagram começa subscrito a comments, live_comments, message_reactions, messages, messaging_optins, messaging_postbacks, messaging_referral e messaging_seen, e Manage cancela a subscrição de qualquer um deles. O botão Test envia uma notificação de exemplo para o campo selecionado.

Como se verifica o X-Hub-Signature-256?

A Meta assina cada notificação de evento com um HMAC-SHA256 do payload, usando como chave o segredo da app, e envia-a em X-Hub-Signature-256 como sha256= seguido do digest hexadecimal. O recetor calcula o mesmo HMAC sobre o corpo bruto do pedido e compara-o com o cabeçalho, em tempo constante. O guia de mensagens da Meta indica que a assinatura abrange o payload com o Unicode escapado, pelo que fazer hash de JSON descodificado ou reserializado dá um resultado diferente.

Node.js: answering verification and checking X-Hub-Signature-256
import crypto from "node:crypto";
import express from "express";

const app = express();
const { VERIFY_TOKEN, APP_SECRET } = process.env;

// Verification request: send hub.challenge back when the token matches
app.get("/webhooks/instagram", (req, res) => {
  const ok = req.query["hub.mode"] === "subscribe" &&
    req.query["hub.verify_token"] === VERIFY_TOKEN;
  if (!ok) return res.sendStatus(403);
  res.status(200).type("text/plain").send(req.query["hub.challenge"]);
});

// Event notification: check the signature over the raw bytes
app.post("/webhooks/instagram", express.raw({ type: "application/json" }), (req, res) => {
  const expected = Buffer.from(
    "sha256=" + crypto.createHmac("sha256", APP_SECRET).update(req.body).digest("hex")
  );
  const given = Buffer.from(req.get("X-Hub-Signature-256") ?? "");
  if (given.length !== expected.length || !crypto.timingSafeEqual(given, expected)) {
    return res.sendStatus(401);
  }
  res.sendStatus(200); // answer first, work after
  const body = JSON.parse(req.body.toString("utf8"));
  // hand body.entry to a queue or background job
});

app.listen(3000);

Porque só o segredo da app pode verificá-la?

Porque a assinatura é um HMAC com essa chave secreta. Sem ela, ninguém consegue calcular o valor esperado, e quem tenha uma cópia de um payload não consegue forjar outro, pelo que a verificação pertence ao servidor que recebe os pedidos da Meta para a app. A Meta pede que os segredos da app, os tokens de acesso e as credenciais de cliente fiquem fora dos registos e dos pedidos de apoio. Um sistema que recebe eventos reencaminhados por outra app não consegue verificar a assinatura da Meta, e depende da assinatura própria dessa app.

Porque é que cada conta precisa da sua própria subscrição?

Porque o painel da app define o que a app pode receber, e as notificações de uma conta só começam quando essa conta também está subscrita. Com Instagram Login, envie POST /<IG_ID>/subscribed_apps para graph.instagram.com com o token de acesso de utilizador do Instagram da conta e com subscribed_fields a listar os campos selecionados para a app, separados por vírgulas. Uma chamada bem-sucedida devolve success com o valor true.

Subscribing one account to comments and messages
POST https://graph.instagram.com/<IG_ID>/subscribed_apps
  ?subscribed_fields=comments,messages
  &access_token=<INSTAGRAM_USER_ACCESS_TOKEN>

{ "success": true }

O que faz a Meta quando as entregas falham?

Tenta novamente e, no fim, desiste. O guia da Meta pede um 200 OK para cada notificação e avisa que o envio em lote, até 1.000 atualizações, não é garantido. Uma atualização falhada é repetida de imediato e depois mais algumas vezes, com frequência decrescente ao longo de 36 horas, e descartada depois disso, pelo que o mesmo evento pode chegar duas vezes. Os eventos de mensagens seguem as regras de entrega de mensagens da Meta, que atuam mais depressa:

  • Espera-se um 200 OK em até 5 segundos; uma entrega falhada é repetida de imediato algumas vezes, pelo que deve deduplicar pelo message mid.
  • Após 15 minutos de falhas, um alerta é enviado para a conta de programador.
  • Após uma hora de falhas, segue-se um alerta Webhooks Disabled, e a app deixa de estar subscrita aos webhooks da conta até voltar a subscrever.
  • As mensagens enviadas durante uma interrupção podem chegar fora de ordem, pelo que devem ser ordenadas pelo timestamp.

O que verificar quando não chega nada?

A lista de verificação de resolução de problemas da Meta, que cobre a maioria dos endpoints silenciosos, por esta ordem:

  • O URL de callback passou na verificação, é acessível por HTTPS e tem um certificado válido; os certificados autoassinados não são suportados.
  • A app selecionou o campo e tem o nível de acesso de que precisa, Advanced Access para comments e live_comments.
  • As notificações estão ativadas para a conta através de subscribed_apps, com um token da mesma configuração de login.
  • A conta cumpre as regras do campo: as notificações de comentários exigem multimédia pertencente a uma conta pública.
  • O servidor devolve success antes de iniciar trabalho lento.

Porque é que a easyCoexistence volta a assinar os eventos reencaminhados?

Porque a assinatura da Meta não pode ser transmitida. A app da easyCoexistence recebe a entrega da Meta, verifica o X-Hub-Signature-256 com o seu próprio segredo da app, responde de imediato à Meta e envia, por POST, cada entrada de uma conta ligada para o endpoint definido para essa conta, dentro de um novo corpo com platform, account_id, external_id e entry. O cabeçalho da Meta não é transmitido e não poderia ser verificado sem esse segredo; por isso, cada reencaminhamento traz Content-Type: application/json e X-EC-Signature, assinado com um segredo que pertence a essa única conta.

Como se verifica o X-EC-Signature?

O cabeçalho tem o formato t=<unix>,v1=<hex>, em que v1 é o HMAC-SHA256 em hexadecimal do timestamp, de um ponto e do corpo bruto, usando como chave o segredo de assinatura da conta. Recalcule sobre os bytes exatamente como recebidos, compare em tempo constante e rejeite um timestamp com mais de 5 minutos.

  • O segredo começa por whsec_ e é mostrado uma única vez, por set_social_webhook_destination ou PUT /channels/:id/webhook, quando o URL é definido.
  • Definir o URL de novo emite um novo segredo, e um URL nulo desativa o reencaminhamento.
  • Cada evento é enviado uma única vez, com espera até 8 segundos, sem seguir redirecionamentos, para um endereço HTTPS que resolve para um IP público.
  • Remover a ligação cancela a subscrição da conta nos webhooks da Meta e apaga o seu endpoint e segredo.
Python: checking X-EC-Signature
import hashlib, hmac, time

def verify_ec_signature(raw_body: bytes, header: str, secret: str) -> bool:
    """Check X-EC-Signature on an event forwarded by easyCoexistence."""
    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    t, v1 = parts.get("t", ""), parts.get("v1", "")
    if not t.isdigit() or abs(time.time() - int(t)) > 300:
        return False  # missing, malformed or older than 5 minutes
    expected = hmac.new(secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected.encode(), v1.encode())

Erros comuns

  • Devolver o challenge como JSON ou entre aspas. A Meta espera o valor de hub.challenge tal como está, como corpo, com estado 200.
  • Fazer hash de um corpo já analisado. Um parser de JSON descarta os bytes exatos que a Meta assinou, por isso guarde o corpo bruto para o HMAC e só depois o analise.
  • Subscrever a app e esquecer a conta. Enquanto POST /<IG_ID>/subscribed_apps não tiver êxito para uma conta, não chega nenhuma notificação dessa conta.
  • Deixar um endpoint falhar durante uma hora. A Meta desativa os webhooks de mensagens e cancela a subscrição da app na conta, que depois tem de ser subscrita de novo.
Fazer isto com a EasyCoexistence

Ative-o com set_social_webhook_destination ou a Partner API. De US$ 9 a US$ 0.75 por ligação por mês, a descer à medida que adiciona ligações, com os primeiros 3 dias gratuitos.

Perguntas frequentes

O que é o hub.challenge nos webhooks do Instagram?

Um inteiro enviado pela Meta no seu GET de verificação. Depois de verificar hub.verify_token, o endpoint devolve-o como corpo da resposta, o que prova que controla o URL.

Porque é que hub.mode e hub.challenge não aparecem em PHP?

O PHP transforma os pontos dos nomes dos parâmetros em sublinhados, pelo que os valores de verificação da Meta chegam como hub_mode, hub_challenge e hub_verify_token.

Como volto a ativar os webhooks do Instagram depois de a Meta os desativar?

Corrija o endpoint e depois volte a subscrever a conta com POST /<IG_ID>/subscribed_apps e os mesmos campos.

Um certificado autoassinado funciona num endpoint de webhook do Instagram?

Não, a Meta não suporta certificados autoassinados: o URL de callback tem de ser acessível por HTTPS com um certificado válido, o primeiro item da lista de resolução de problemas da Meta.

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