Eventos de webhook do Instagram: comentários, menções e DMs
Os eventos de webhook do Instagram informam a atividade de uma conta profissional assim que ela acontece: novos comentários, @menções e DMs. A Meta envia cada um como JSON para o endpoint HTTPS do app conectado e repete, por até 36 horas, a entrega que falhou nesse endpoint. O easyCoexistence repassa cada evento ao seu endpoint uma única vez, assinado por conta, sem repetições. Com o Instagram Login, as menções chegam dentro da notificação de comentários.
Por quanto tempo a Meta continua repetindo uma entrega com falha ao endpoint do app antes de descartá-la.
A maioria das atualizações a Meta agrupa em uma única entrega de webhook, embora não garanta o agrupamento.
Sinalizador que a Meta define em eventos de mensagem enviados pela própria conta.
Só mídias de contas públicas disparam notificações de comentários e menções.
Quais são os eventos?
Para uma conta profissional conectada com o Instagram Login, três tipos de atividade chegam como eventos:
- Comentários: um novo comentário em uma mídia da conta, com o ID do comentário, o ID do autor no escopo do Instagram e o nome de usuário, o texto, além do ID e do tipo da mídia.
- Menções: com o Instagram Login, chegam dentro da notificação de comentários, e não como um campo próprio.
- Mensagens: uma DM enviada à conta, com o remetente, o destinatário, um carimbo de data e hora e a mensagem em si, incluindo texto, anexos e respostas a Stories.
Como os eventos chegam ao seu endpoint?
A Meta entrega os webhooks do Instagram ao app ao qual a conta se conectou. O easyCoexistence os recebe e repassa cada um ao endpoint HTTPS que você definiu para essa conta, assim que chegam, assinado com um segredo dessa conta.
Defina o endpoint com set_social_webhook_destination pelo Claude ou pelo ChatGPT, ou com a Partner API por meio de PUT /channels/:id/webhook. O segredo de assinatura é exibido uma única vez, definir o endpoint de novo gera um novo, e passar null como URL desliga o repasse.
Como é uma entrega?
Um POST com corpo JSON contendo a plataforma, o account_id que list_social_accounts devolve para a conexão, o external_id da conta do Instagram e entry: a entrada de webhook da Meta para o evento, sem alterações. Uma DM chega do mesmo jeito, com um array messaging no lugar de changes. Um novo comentário tem esta forma:
{
"platform": "instagram",
"account_id": "<ACCOUNT_ID>",
"external_id": "<INSTAGRAM_ACCOUNT_ID>",
"entry": {
"id": "<INSTAGRAM_ACCOUNT_ID>",
"time": 1793318400,
"changes": [
{
"field": "comments",
"value": {
"id": "<COMMENT_ID>",
"from": { "id": "<INSTAGRAM_SCOPED_ID>", "username": "<USERNAME>" },
"text": "<COMMENT_TEXT>",
"media": { "id": "<MEDIA_ID>", "media_product_type": "<MEDIA_PRODUCT_TYPE>" }
}
}
]
}
}Como você verifica uma entrega?
Cada entrega traz um cabeçalho X-EC-Signature no formato t=<unix>,v1=<hex>, em que v1 é o HMAC-SHA256 do timestamp, de um ponto e do corpo bruto da requisição, usando como chave o segredo de assinatura da conta. Calcule sobre o corpo bruto exatamente como recebido, compare em tempo constante e rejeite um timestamp com mais de 5 minutos.
import crypto from "node:crypto";
// rawBody: the request body exactly as received, as a string
export function verify(rawBody, header, secret) {
const sig = Object.fromEntries(header.split(",").map((part) => part.split("=")));
if (!sig.t || !sig.v1) return false;
if (Math.abs(Date.now() / 1000 - Number(sig.t)) > 300) return false;
const expected = crypto
.createHmac("sha256", secret)
.update(sig.t + "." + rawBody)
.digest("hex");
return expected.length === sig.v1.length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig.v1));
}A entrega é repetida?
Não pelo easyCoexistence: o repasse envia cada evento uma única vez, em memória, e não guarda cópia para repetir. Responda com 2xx rapidamente e faça o trabalho depois, e armazene o que precisar assim que ela chegar, já que a Meta também não mantém um histórico de notificações passadas que possa ser consultado.
A própria Meta repete uma entrega com falha ao app por até 36 horas, então o mesmo evento pode chegar duas vezes de vez em quando: deduplique pelo ID do comentário ou pelo mid da mensagem.
O que mais um handler deve verificar?
Alguns detalhes dos payloads da Meta que pegam de surpresa um primeiro handler:
is_echo: um evento de mensagem comis_echodefinido como true foi enviado pela própria conta, então não precisa de resposta.- Respostas a Stories: uma DM que responde a um Story traz
reply_tocom o ID e a URL do Story. - Menções em Stories: chegam como uma mensagem cujo tipo de anexo é
story_mention. - time: quando a Meta enviou a notificação, não quando o comentário ou a mensagem foi feito; o carimbo da mensagem fica na própria entrada messaging.
- IDs de álbum: os eventos de comentário não os incluem; busque o álbum com o ID do comentário.
Erros comuns
- Fazer o trabalho antes de responder. O repasse não repete, então devolva um 2xx imediatamente e processe o evento depois.
- Verificar a assinatura sobre o JSON já parseado. Calcule o HMAC sobre o corpo bruto exatamente como chegou.
- Responder a eventos echo. Um evento de mensagem com is_echo definido é uma mensagem enviada pela conta, e responder a ela inicia um loop.
- Pular a deduplicação. A Meta pode entregar o mesmo evento de novo após uma falha, então use como chave o ID do comentário ou o mid da mensagem.
O easyCoexistence repassa os comentários, as menções e as DMs da conta do Instagram ao seu endpoint HTTPS assim que chegam, assinados com um segredo dessa conta e sem guardar cópia no caminho. Ative com set_social_webhook_destination pelo Claude ou pelo ChatGPT, ou com a Partner API. De US$ 9 a US$ 0.75 por conexão por mês, com o valor caindo conforme você adiciona conexões, e os 3 primeiros 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 significa o campo time em um webhook do Instagram?
Quando a Meta enviou a notificação, não quando o comentário ou a mensagem foi feito. O carimbo da própria DM fica na sua entrada messaging.
A Meta repete entregas de webhook do Instagram que falharam?
Sim. A Meta repete uma entrega com falha ao app por até 36 horas, então o mesmo evento pode chegar duas vezes de vez em quando: deduplique pelo ID do comentário ou pelo mid da mensagem. O easyCoexistence repassa cada evento ao seu endpoint uma única vez, então responda com um 2xx rapidamente.
Quantas atualizações uma entrega de webhook do Instagram pode conter?
Até 1.000 quando a Meta as agrupa, embora a Meta não garanta o agrupamento. Percorra todo o array entry em vez de ler apenas o primeiro item.
As menções têm evento próprio?
Não com o Instagram Login. A Meta inclui as menções na notificação de comentários, então elas chegam pelo mesmo caminho que os comentários.
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