Webhooks de redes sociais: comentários, menções e mensagens para um só endpoint
A easyCoexistence reencaminha os eventos das redes sociais para o seu próprio endpoint HTTPS à medida que acontecem: comentários, menções e DMs do Instagram e do Facebook, e comentários do TikTok. Cada evento chega num único envelope, com o evento original da rede inalterado no interior, assinado por conta com X-EC-Signature. Ative-o por conta com set_social_webhook_destination, a partir do Claude ou do ChatGPT, ou com a Partner API. As mensagens de um número do WhatsApp também chegam ao seu servidor.
- Comentários, menções e DMs em tempo real
- Um envelope, assinado por cada conta
- Definido a partir do Claude, do ChatGPT ou da Partner API
Nada é cobrado durante 3 dias. Cancele quando quiser.
Quantas vezes a easyCoexistence envia cada evento social reencaminhado; não guarda cópia, por isso nada é reenviado mais tarde.
Em quanto tempo o webhook comment.update do TikTok comunica que um comentário foi criado, eliminado ou alterou a visibilidade nos vídeos públicos de uma conta própria.
Onde as aplicações no Instagram Login recebem as @menções: dentro da notificação do webhook de comentários, e não num campo próprio.
O que as notificações push do YouTube comunicam sobre um canal: um novo carregamento, um novo título ou uma nova descrição.
Durante quanto tempo a Meta continua a voltar a tentar a entrega de um webhook do WhatsApp que o seu servidor não aceitou, o que pode originar duplicados.
Que eventos envia cada rede?
O Instagram, o Facebook e o TikTok enviam eventos à easyCoexistence, que transmite cada um para o URL definido para essa conta. O Instagram envia novos comentários, com as @menções a chegarem dentro da notificação de comentários, e DMs. Uma Página do Facebook envia a atividade do feed, que inclui os novos comentários, além das mensagens do Messenger e das menções à Página. O TikTok envia comment.update, disparado quando um comentário é criado, eliminado ou muda de visibilidade.
O YouTube e o LinkedIn não enviam à easyCoexistence eventos de comentários nem de mensagens, por isso um agente lê os respetivos comentários quando lhe são pedidos. Um número do WhatsApp funciona por um caminho próprio: a Meta entrega as mensagens diretamente ao seu servidor, ou a easyCoexistence reencaminha-as assinadas quando o número funciona em modo gerido.
| What arrives | Sent by | |
|---|---|---|
| Comments, mentions and DMs | easyCoexistence, signed per account | |
| Feed activity, Messenger and mentions | easyCoexistence, signed per account | |
| TikTok | comment.update events | easyCoexistence, signed per account |
| Messages and echoes from the app | Meta directly, or easyCoexistence in managed mode | |
| YouTube | No comment events | Read with list_youtube_comments |
| No comment events | Read with list_linkedin_comments |
Como é um evento reencaminhado?
O envelope JSON é igual em cada rede, enviado com Content-Type application/json: platform, a rede; account_id, o ID que as ferramentas MCP e a Partner API usam; external_id, o ID da conta na rede; e entry, o evento próprio da rede tal como chegou. No Instagram e no Facebook, entry é a entrada de webhook da Meta, com changes para comentários e menções e messaging para as DMs. No TikTok contém o evento comment.update, com comment_id, video_id e parent_comment_id como strings, para que os IDs de 64 bits não sejam arredondados. Uma mensagem do Messenger chega assim:
{
"platform": "facebook",
"account_id": "<ACCOUNT_ID>",
"external_id": "<PAGE_ID>",
"entry": {
"id": "<PAGE_ID>",
"time": 1793318400512,
"messaging": [
{
"sender": { "id": "<PAGE_SCOPED_ID>" },
"recipient": { "id": "<PAGE_ID>" },
"timestamp": 1793318399870,
"message": { "mid": "<MESSAGE_ID>", "text": "Are you open on Sunday?" }
}
]
}
}Como verifica o X-EC-Signature?
Com o segredo de assinatura devolvido ao definir o destino, único para essa conta e mostrado uma só vez. O cabeçalho tem a forma t=<unix>,v1=<hex>, e v1 é um HMAC-SHA256 do timestamp, um ponto e o corpo bruto do pedido, com essa chave secreta. Leia o corpo como bytes antes de o analisar, recuse um timestamp com mais de 5 minutos de diferença do seu relógio, procure o segredo pelo account_id do evento e compare os dois resumos em tempo constante. Depois responda com 2xx e coloque o trabalho numa fila. Em PHP, são necessárias algumas linhas:
<?php
// POST /hooks/social: one endpoint for the events of each account
$raw = file_get_contents('php://input'); // the exact bytes that were signed
parse_str(str_replace(',', '&', $_SERVER['HTTP_X_EC_SIGNATURE'] ?? ''), $sig);
$event = json_decode($raw, true); // platform, account_id, external_id, entry
$secret = secret_for($event['account_id'] ?? ''); // the signing_secret stored for that account
$fresh = ctype_digit($sig['t'] ?? '') && abs(time() - (int) $sig['t']) <= 300;
$expected = hash_hmac('sha256', ($sig['t'] ?? '') . '.' . $raw, (string) $secret);
if (!$secret || !$fresh || !hash_equals($expected, $sig['v1'] ?? '')) {
http_response_code(401);
exit;
}
http_response_code(204);
enqueue($event); // keep this quick: the forward waits 8 seconds and is never resentComo ativa o reencaminhamento para uma conta?
A partir de um assistente ou do seu servidor. Peça ao Claude ou ao ChatGPT que execute set_social_webhook_destination com a conta e o seu URL HTTPS, ou chame PUT /api/v1/channels/:id/webhook na Partner API com a sua chave ec_live_ e um corpo com o url. Ambos devolvem o signing_secret da conta uma só vez, por isso guarde-o então associado ao account_id. Se voltar a chamar qualquer um, é emitido um novo segredo, e um url com valor null desativa o reencaminhamento.
O URL tem de ser HTTPS num host público: um endereço privado é recusado ao defini-lo e de novo na entrega. Um só endpoint pode servir várias contas, pois cada evento indica o respetivo account_id. Para um número do WhatsApp, set_webhook_destination encaminha as entregas da Meta para si, e set_inbound_mode com um forward_url passa a reencaminhá-las assinadas.
O que acontece quando o seu endpoint está lento ou em baixo?
O evento não é reenviado. A easyCoexistence faz uma única tentativa, espera até 8 segundos por uma resposta, não segue redirecionamentos e não guarda cópia, porque repetir implicaria guardar os comentários e mensagens dos seus clientes. Responda 2xx assim que a assinatura estiver validada, faça o trabalho lento a partir de uma fila e elimine os duplicados com base nos IDs da própria rede, como o ID de um comentário ou o mid de uma mensagem, caso um evento chegue duas vezes.
O WhatsApp é diferente. No modo direto, a Meta volta a tentar uma entrega que o seu servidor não aceitou durante até 7 dias. No modo gerido, a easyCoexistence coloca as mensagens em fila para o seu URL de reencaminhamento e volta a tentar com intervalos crescentes. Os eventos de estado do Partner, como quando uma ligação cai, são repetidos durante cerca de 33 horas.
Como chegam os comentários do YouTube e do LinkedIn a um agente?
Lendo-os segundo uma agenda. As notificações push do YouTube comunicam um novo carregamento, um novo título ou uma nova descrição, não comentários, e a easyCoexistence não recebe eventos de comentários do LinkedIn; por isso nenhuma das duas reencaminha nada. O agente verifica em vez disso: list_youtube_comments devolve as conversas de um vídeo ou de todo o canal, incluindo as que estão retidas para revisão, e list_linkedin_comments devolve os comentários de uma publicação ou as respostas a um deles. No n8n, Make ou Zapier, um gatilho de agenda inicia a verificação; no seu próprio código, uma tarefa cron obtém as credenciais do canal e chama diretamente o endpoint commentThreads do YouTube ou o endpoint de comentários do LinkedIn.
Como configurar
- Set the destinationRun set_social_webhook_destination with the account and an HTTPS URL, or call PUT /api/v1/channels/:id/webhook with your ec_live_ key.
- Store the secretSave the signing_secret from the response against that account_id, since it is shown only once.
- Verify each deliveryCheck that the timestamp is fresh and that v1 matches an HMAC-SHA256 of the timestamp, a dot and the raw body.
- Acknowledge, then workAnswer 2xx straight away and hand the event to a queue, because easyCoexistence sends it only once.
Erros comuns
- Verificar o HMAC sobre o JSON já analisado. A assinatura cobre o corpo bruto byte a byte, e voltar a serializar o objeto analisado altera esses bytes; por isso verifique antes de analisar.
- Usar um só segredo para todas as contas. Cada conta assina com o seu próprio segredo, por isso procure-o pelo account_id do evento antes de comparar o v1.
- Definir o destino de novo sem atualizar o seu endpoint. Cada chamada emite um novo segredo e o anterior deixa de assinar de imediato, por isso guarde o novo logo.
- Indicar um URL que redireciona. Os reencaminhamentos não seguem redirecionamentos, por isso uma mudança de caminho ou de host faz perder o evento; defina o endereço final.
A easyCoexistence envia comentários, menções e DMs do Instagram e do Facebook, e comentários do TikTok, para o seu endpoint em tempo real, assinados por conta, e encaminha as mensagens do WhatsApp para o seu servidor, para que os seus agentes de IA ouçam os clientes através da API oficial de cada rede, com cada ligação monitorizada 24/7. 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
Como chegam as mensagens de um número do WhatsApp ao meu endpoint?
De uma de duas formas. set_webhook_destination faz com que a Meta as entregue diretamente ao seu servidor, enquanto set_inbound_mode com um forward_url faz com que a easyCoexistence as reencaminhe assinadas com X-EC-Signature, voltando a tentar com intervalos crescentes.
Pode o mesmo evento chegar duas vezes?
Pode, por isso elimine os duplicados com base nos IDs da própria rede, como o ID de um comentário ou o mid de uma mensagem. As repetições da Meta de uma entrega do WhatsApp que o seu servidor não aceitou, durante até 7 dias, também podem originar duplicados.
Pode um só endpoint receber eventos de várias contas?
Pode. Cada evento inclui platform e account_id, por isso um só URL pode servir várias contas, desde que verifique cada assinatura com o segredo próprio dessa conta.
Quanto custam os webhooks de redes sociais da easyCoexistence?
De US$ 9 a US$ 0.75 por ligação por mês, descendo à medida que acrescenta ligações, com o mesmo preço em todas as redes. O reencaminhamento, o servidor MCP e a Partner API estão incluídos, com os primeiros 3 dias grátis.
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