Eventos de webhook do Instagram: comentários, menções e DMs
Os eventos webhook do Instagram comunicam a atividade de uma conta profissional à medida que acontece: novos comentários, @menções e DMs. A Meta envia cada um, em JSON, por POST para o endpoint HTTPS da aplicação ligada, e volta a tentar uma entrega falhada a esse endpoint durante até 36 horas. A easyCoexistence reencaminha cada evento para o seu endpoint uma única vez, assinado por conta, sem novas tentativas. Com o Instagram Login, as menções chegam dentro da notificação de comentários.
Durante quanto tempo a Meta volta a tentar uma entrega falhada ao endpoint da aplicação antes de a descartar.
A maioria das atualizações a Meta agrupa numa única entrega de webhook, embora não garanta esse agrupamento.
A marca que a Meta define nos eventos de mensagem enviados pela própria conta.
Só os conteúdos de contas públicas acionam as notificações de comentários e de menções.
Que eventos existem?
Numa conta profissional ligada com o Instagram Login, três tipos de atividade chegam como eventos:
- Comentários: um novo comentário nos conteúdos multimédia da conta, com o ID do comentário, o ID do autor no Instagram e o nome de utilizador, o texto, e o ID e o tipo do conteúdo multimé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, uma marca temporal e a própria mensagem, incluindo texto, anexos e respostas a Stories.
Como chegam os eventos ao seu endpoint?
A Meta entrega os webhooks do Instagram à aplicação a que a conta se ligou. O easyCoexistence recebe-os e reencaminha cada um, à medida que chega, para o endpoint HTTPS que definiu para essa conta, assinado com um segredo próprio dessa conta.
Defina o endpoint com set_social_webhook_destination a partir do Claude ou do ChatGPT, ou com a Partner API através de PUT /channels/:id/webhook. O segredo de assinatura é mostrado uma única vez, definir de novo o endpoint emite um novo, e passar null como URL desativa o reencaminhamento.
Como é uma entrega?
Um POST com um corpo JSON que contém a plataforma, o account_id que list_social_accounts devolve para a ligaçã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 da mesma forma, com um array messaging em vez de changes. Um novo comentário tem este aspeto:
{
"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 se verifica uma entrega?
Cada entrega traz um cabeçalho X-EC-Signature no formato t=<unix>,v1=<hex>, em que v1 é o HMAC-SHA256 da marca temporal, de um ponto e do corpo bruto do pedido, com o segredo de assinatura da conta como chave. Calcule-o sobre o corpo bruto exatamente como foi recebido, compare em tempo constante e rejeite uma marca temporal mais antiga do que 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?
O easyCoexistence não a repete: o reencaminhamento passa cada evento uma só vez, em memória, e não guarda cópia para voltar a tentar. Responda com um 2xx rapidamente e faça o trabalho depois, e guarde o que precisar quando chegar, já que a Meta também não mantém um histórico consultável das notificações anteriores.
A própria Meta volta a tentar uma entrega falhada à aplicação durante até 36 horas, por isso o mesmo evento pode, ocasionalmente, chegar-lhe duas vezes: elimine os duplicados pelo ID do comentário ou pelo mid da mensagem.
O que deve verificar um manipulador?
Alguns detalhes dos payloads da Meta que fazem tropeçar um primeiro manipulador:
is_echo: um evento de mensagem comis_echoa true foi enviado pela própria conta, por isso não precisa de resposta.- Respostas a Stories: uma DM que responde a uma Story traz
reply_tocom o ID e o URL da Story. - Menções em Stories: chegam como uma mensagem cujo tipo de anexo é
story_mention. - time: o momento em que a Meta enviou a notificação, e não quando o comentário ou a mensagem foram feitos; a marca temporal da própria mensagem está na sua entrada messaging.
- IDs de álbuns: os eventos de comentário não os incluem; procure o álbum com o ID do comentário.
Erros comuns
- Fazer o trabalho antes de responder. O reencaminhamento não volta a tentar, por isso devolva um 2xx de imediato e processe o evento depois.
- Verificar a assinatura sobre JSON já analisado. Calcule o HMAC sobre o corpo bruto exatamente como chegou.
- Responder aos ecos. Um evento de mensagem com is_echo definido é uma mensagem enviada pela conta, e responder-lhe inicia um ciclo.
- Saltar a eliminação de duplicados. A Meta pode voltar a entregar o mesmo evento após uma falha, por isso use como chave o ID do comentário ou o mid da mensagem.
O easyCoexistence reencaminha os comentários, as menções e as DMs da conta do Instagram para o seu endpoint HTTPS à medida que chegam, assinados com um segredo próprio da conta e sem guardar cópia pelo caminho. Ative-o com set_social_webhook_destination a partir do Claude ou do ChatGPT, ou com a Partner API. De US$ 9 a US$ 0.75 por ligação por mês, descendo à medida que acrescenta ligações, com os primeiros 3 dias grátis.
Perguntas frequentes
O que significa o campo time num webhook do Instagram?
O momento em que a Meta enviou a notificação, e não quando o comentário ou a mensagem foram feitos. A marca temporal da própria DM está na sua entrada messaging.
A Meta volta a tentar entregas de webhook do Instagram que falharam?
Sim. A Meta volta a tentar uma entrega falhada à aplicação durante até 36 horas, por isso o mesmo evento pode, ocasionalmente, chegar duas vezes: elimine os duplicados pelo ID do comentário ou pelo mid da mensagem. O easyCoexistence reencaminha cada evento para o seu endpoint uma só vez, por isso responda com um 2xx rapidamente.
Quantas atualizações pode ter uma entrega de webhook do Instagram?
Até 1 000 quando a Meta as agrupa, embora a Meta não garanta esse 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, por isso chegam pelo mesmo caminho que os comentários.
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