Verificação de webhook do Instagram: hub.challenge e X-Hub-Signature-256
Configurar webhooks do Instagram exige um endpoint HTTPS que responde ao GET de verificação da Meta, que traz hub.mode definido como subscribe, hub.verify_token e hub.challenge, verificando o token e devolvendo o hub.challenge. Depois, a Meta envia por POST eventos JSON assinados em X-Hub-Signature-256 com o segredo do app, assim que o app assina os campos e cada conta é assinada pelo edge subscribed_apps.
O easyCoexistence cuida do lado da Meta: seu app passa na verificação, valida o X-Hub-Signature-256, assina cada conta do Instagram conectada para comentários, mensagens e menções, e encaminha os eventos para o seu endpoint HTTPS assinados com X-EC-Signature e um segredo por conta, monitorando cada conexão o tempo todo.
O hub.mode sempre vem na requisição de verificação da Meta.
Período em que a Meta repete uma notificação com falha, com frequência cada vez menor, antes de descartá-la.
De entregas de mensagens com falha antes que a Meta envie um alerta à conta de desenvolvedor.
De entregas de mensagens com falha antes do alerta Webhooks Disabled e do cancelamento da assinatura do app na conta.
Modo do app que a Meta exige antes que um app receba notificações das contas de seus usuários.
Como funciona a configuração de webhooks do Instagram?
Em quatro etapas, na ordem que o guia da Meta indica. O endpoint precisa passar na verificação antes que qualquer campo possa ser selecionado, o app precisa estar Live para receber notificações das contas de seus usuários, e a verificação de negócio é exigida para acesso à produção.
O que a requisição de verificação contém?
Um GET para a URL de callback, enviado sempre que o produto Webhooks é configurado no App Dashboard. Quando hub.verify_token coincide com o token do próprio endpoint, a resposta é um 200 com o valor de hub.challenge como corpo inteiro; caso contrário, um 403. O App Dashboard informa se o endpoint passou.
- hub.mode: sempre subscribe.
- hub.challenge: um inteiro gerado pela Meta, que o endpoint precisa devolver.
- hub.
verify_token: a string informada no campo Verify Token do dashboard, que só a Meta e o endpoint devem conhecer. - Em PHP, os pontos desses nomes viram underscores, então 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 a URL de callback e os campos são definidos?
No App Dashboard, em Instagram, API setup with Instagram login, Configure webhooks: a URL de callback e o verify token vão ali, e salvá-los dispara a requisição de verificação. O produto Instagram começa assinado em comments, live_comments, message_reactions, messages, messaging_optins, messaging_postbacks, messaging_referral e messaging_seen, e Manage cancela a assinatura de qualquer um deles. O botão Test envia uma notificação de exemplo para um campo selecionado.
Como o X-Hub-Signature-256 é verificado?
A Meta assina cada notificação de evento com um HMAC-SHA256 do payload, chaveado com o segredo do app, e envia a assinatura em X-Hub-Signature-256 como sha256= seguido do digest hexadecimal. O receptor calcula o mesmo HMAC sobre o corpo bruto da requisição e o compara com o cabeçalho em tempo constante. O guia de mensagens da Meta observa que a assinatura cobre o payload com o Unicode escapado, então hashear JSON decodificado 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);Por que só o segredo do app consegue verificar?
Porque a assinatura é um HMAC chaveado com esse segredo. Sem ele, ninguém consegue calcular o valor esperado, e quem tiver uma cópia de um payload não consegue forjar outro, então a verificação pertence ao servidor que recebe as requisições da Meta para o app. A Meta pede que segredos do app, tokens de acesso e credenciais de cliente fiquem fora de logs e de chamados de suporte. Um sistema que recebe eventos repassados por outro app não consegue verificar a assinatura da Meta, e depende da assinatura própria desse app.
Por que cada conta precisa de uma assinatura própria?
Porque o App Dashboard define o que o app pode receber, e as notificações de uma conta só começam quando essa conta também é assinada. Com Instagram Login, envie POST /<IG_ID>/subscribed_apps para graph.instagram.com com o token de acesso de usuário do Instagram da conta e subscribed_fields listando os campos selecionados para o app, separados por vírgulas. Uma chamada bem-sucedida retorna success definido como true.
POST https://graph.instagram.com/<IG_ID>/subscribed_apps
?subscribed_fields=comments,messages
&access_token=<INSTAGRAM_USER_ACCESS_TOKEN>
{ "success": true }O que a Meta faz quando as entregas falham?
Ela repete e depois desiste. O guia da Meta pede um 200 OK para cada notificação e avisa que o agrupamento em lotes, de até 1,000 atualizações, não é garantido. Uma atualização com falha é repetida na hora e mais algumas vezes, com frequência cada vez menor, ao longo de 36 horas, e descartada depois disso, então o mesmo evento pode chegar duas vezes. Os eventos de mensagens seguem as regras de entrega de mensagens da Meta, que agem mais rápido:
- Espera-se um 200 OK em até 5 segundos, e uma entrega com falha recebe algumas repetições imediatas, então deduplique pelo mid da mensagem.
- Após 15 minutos de falhas, um alerta é enviado para a conta de desenvolvedor.
- Após uma hora de falhas, segue um alerta Webhooks Disabled, e a assinatura do app nos webhooks da conta é cancelada até que ele assine de novo.
- Mensagens enviadas durante uma indisponibilidade podem chegar fora de ordem, então ordene-as pelo timestamp.
O que verificar quando nada chega?
A lista de verificação de solução de problemas da Meta, que cobre a maioria dos endpoints silenciosos, nesta ordem:
- A URL de callback passou na verificação e é acessível por HTTPS com um certificado válido; certificados autoassinados não são suportados.
- O app selecionou o campo e tem o nível de acesso necessário, Advanced Access para comments e
live_comments. - As notificações estão habilitadas para a conta por meio de
subscribed_apps, com um token da mesma configuração de login. - A conta atende às regras do campo: notificações de comentários exigem mídia de uma conta pública.
- O servidor retorna sucesso antes de começar trabalho lento.
Por que o easyCoexistence assina de novo os eventos encaminhados?
Porque a assinatura da Meta não pode ser repassada. O app do easyCoexistence recebe a entrega da Meta, verifica o X-Hub-Signature-256 com o próprio segredo do app, responde à Meta na hora e envia por POST cada entrada de uma conta conectada ao 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 é repassado e não poderia ser verificado sem esse segredo, então cada encaminhamento leva Content-Type: application/json e X-EC-Signature, chaveado com um segredo que pertence àquela única conta.
Como verificar o X-EC-Signature?
O cabeçalho tem o formato t=<unix>,v1=<hex>, em que v1 é o HMAC-SHA256 em hexadecimal do timestamp, um ponto e o corpo bruto, chaveado com 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 com whsec_ e é exibido uma única vez, por
set_social_webhook_destinationou PUT /channels/:id/webhook, quando a URL é definida. - Definir a URL de novo emite um novo segredo, e uma URL nula desliga o encaminhamento.
- Cada evento é enviado uma vez, aguardando até 8 segundos, sem seguir redirecionamentos, para um endereço HTTPS que resolve para um IP público.
- Remover a conexão cancela a assinatura da conta nos webhooks da Meta e limpa seu endpoint e seu 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 em si como corpo, com status 200.
- Hashear um corpo já parseado. Um parser de corpo JSON descarta os bytes exatos que a Meta assinou, então guarde o corpo bruto para o HMAC e faça o parse depois.
- Assinar o app e esquecer a conta. Até que POST /<IG_ID>/subscribed_apps tenha sucesso para uma conta, nenhuma notificação chega para ela.
- Deixar o endpoint falhar por uma hora. A Meta desativa os webhooks de mensagens e cancela a assinatura do app na conta, que então precisa ser assinada de novo.
Ative com set_social_webhook_destination ou pela Partner API. De US$ 9 a US$ 0.75 por conexão por mês, com redução conforme você adiciona conexões, e os primeiros 3 dias são 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
O que é hub.challenge nos webhooks do Instagram?
Um inteiro que a Meta envia na sua requisição GET de verificação. Depois de checar hub.verify_token, o endpoint devolve esse valor como corpo da resposta, o que comprova que ele controla a URL.
Por que hub.mode e hub.challenge somem em PHP?
O PHP troca os pontos nos nomes dos parâmetros por underscores, então os valores de verificação da Meta chegam como hub_mode, hub_challenge e hub_verify_token.
Como reativar os webhooks do Instagram depois que a Meta os desativa?
Corrija o endpoint e depois assine a conta de novo com POST /<IG_ID>/subscribed_apps e os mesmos campos.
Um certificado autoassinado funciona no endpoint de webhook do Instagram?
Não. A Meta não suporta certificados autoassinados: a URL de callback precisa ser acessível por HTTPS com um certificado válido, o primeiro item da lista de solução de problemas da Meta.
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