EntrarComeçar teste grátis
easyCoexistence APIs oficiais

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.

subscribe

O hub.mode sempre vem na requisição de verificação da Meta.

36 hours

Período em que a Meta repete uma notificação com falha, com frequência cada vez menor, antes de descartá-la.

15 minutes

De entregas de mensagens com falha antes que a Meta envie um alerta à conta de desenvolvedor.

1 hour

De entregas de mensagens com falha antes do alerta Webhooks Disabled e do cancelamento da assinatura do app na conta.

Live

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.

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 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_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 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.

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);

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.

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 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_destination ou 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.
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 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.
Fazendo isso com o EasyCoexistence

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