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.
O valor hub.mode está sempre presente no pedido de verificação da Meta.
Período durante o qual a Meta volta a tentar uma notificação falhada, com frequência decrescente, antes de a descartar.
De entregas de mensagens com falha antes de a Meta enviar um alerta para a conta de programador.
De entregas de mensagens com falha antes de um alerta Webhooks Disabled e do cancelamento da subscrição da app na conta.
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.
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_challengeehub_verify_token.
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
1158201444Onde 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.
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.
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_destinationou 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.
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.
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