EntrarComeçar teste grátis
easyCoexistence APIs oficiais

Webhooks de redes sociais: comentários, menções e mensagens para um endpoint

O easyCoexistence encaminha eventos de redes sociais para o seu próprio endpoint HTTPS assim que acontecem: comentários, menções e DMs do Instagram e do Facebook, e comentários do TikTok. Cada evento chega em um envelope, com o evento original da rede sem alterações, assinado por conta com X-EC-Signature. Ative por conta com set_social_webhook_destination no Claude ou no 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 para cada conta
  • Configure pelo Claude, ChatGPT ou Partner API
Começar teste grátis

Nada é cobrado por 3 dias. Cancele quando quiser.

Só APIs oficiaisMCP para Claude e ChatGPTToda conexão monitorada 24/73 dias grátis
1 attempt

Quantas vezes o easyCoexistence envia cada evento social encaminhado; ele não guarda cópia, então nada é reenviado depois.

Within 5 minutes

Em que prazo o webhook comment.update do TikTok informa que um comentário foi criado, excluído ou teve a visibilidade alterada nos vídeos públicos de uma conta sua.

In comments

Onde apps no Instagram Login recebem as @menções: dentro da notificação do webhook de comentários, e não como um campo próprio.

3 events

O que as notificações push do YouTube informam sobre um canal: um novo upload, um novo título ou uma nova descrição.

7 days

Por quanto tempo a Meta continua repetindo um webhook do WhatsApp que o seu servidor não aceitou, o que pode gerar entregas duplicadas.

Quais eventos cada rede envia?

Instagram, Facebook e TikTok enviam eventos ao easyCoexistence, que repassa cada um para a URL que você definiu para aquela conta. O Instagram envia novos comentários, com as @menções chegando dentro da notificação de comentários, e DMs. Uma Página do Facebook envia a atividade do feed, que cobre novos comentários, além de mensagens do Messenger e menções à Página. O TikTok envia comment.update, disparado quando um comentário é criado, excluído ou tem a visibilidade alterada.

O YouTube e o LinkedIn não enviam ao easyCoexistence eventos de comentários ou mensagens, então um agente lê os comentários deles sob demanda. Um número do WhatsApp funciona por um caminho próprio: a Meta entrega as mensagens diretamente ao seu servidor, ou o easyCoexistence as encaminha assinadas quando o número roda em modo gerenciado.

What arrivesSent by
InstagramComments, mentions and DMseasyCoexistence, signed per account
FacebookFeed activity, Messenger and mentionseasyCoexistence, signed per account
TikTokcomment.update eventseasyCoexistence, signed per account
WhatsAppMessages and echoes from the appMeta directly, or easyCoexistence in managed mode
YouTubeNo comment eventsRead with list_youtube_comments
LinkedInNo comment eventsRead with list_linkedin_comments

Como é um evento encaminhado?

O mesmo envelope JSON 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 como chegou. Para Instagram e Facebook, entry é a entrada de webhook da Meta, com changes para comentários e menções e messaging para DMs. Para o TikTok, ele traz o evento comment.update, com comment_id, video_id e parent_comment_id como strings, para que IDs de 64 bits não sejam arredondados. Uma mensagem do Messenger chega assim:

A forwarded Messenger message, trimmed
{
  "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 verificar o X-EC-Signature?

Com o segredo de assinatura devolvido quando você define o destino, exclusivo daquela conta e exibido uma única vez. O cabeçalho tem o formato t=<unix>,v1=<hex>, e v1 é um HMAC-SHA256 do timestamp, de um ponto e do corpo bruto da requisição, com o segredo como chave. Leia o corpo como bytes antes de fazer o parse, recuse um timestamp com mais de 5 minutos de diferença do seu relógio, busque o segredo pelo account_id do evento e compare os dois digests em tempo constante. Depois responda 2xx e coloque o trabalho em fila. Em PHP, isso leva poucas linhas:

PHP: verifying a forwarded event
<?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 resent

Como ativar o encaminhamento para uma conta?

A partir de um assistente ou do seu backend. Peça ao Claude ou ao ChatGPT para executar set_social_webhook_destination com a conta e a sua URL HTTPS, ou chame PUT /api/v1/channels/:id/webhook na Partner API com a sua chave ec_live_ e um corpo com a url. Os dois devolvem o signing_secret da conta uma única vez, então guarde-o junto ao account_id naquele momento. Chamar qualquer um dos dois de novo gera um novo segredo, e uma url igual a null desliga o encaminhamento.

A URL precisa ser HTTPS em um host público: um endereço privado é recusado ao ser definido e de novo na entrega. Um único endpoint pode atender várias contas, já que cada evento informa seu account_id. Para um número do WhatsApp, set_webhook_destination direciona as entregas da Meta para você, e set_inbound_mode com um forward_url as encaminha assinadas.

O que acontece quando o seu endpoint está lento ou fora do ar?

O evento não é reenviado. O easyCoexistence faz uma única tentativa, aguarda até 8 segundos por uma resposta, não segue redirecionamentos e não guarda cópia, porque repetir significaria armazenar comentários e mensagens dos seus clientes. Responda 2xx assim que a assinatura for validada, faça o trabalho lento a partir de uma fila e deduplique pelos IDs da própria rede, como um ID de comentário ou um message mid, caso um evento chegue duas vezes.

O WhatsApp é diferente. No modo direto, a Meta repete uma entrega que o seu servidor não aceitou por até 7 dias. No modo gerenciado, o easyCoexistence enfileira as mensagens para a sua URL de encaminhamento e repete com backoff. Eventos de status da Partner API, como uma conexão caindo, são repetidos por cerca de 33 horas.

Como os comentários do YouTube e do LinkedIn chegam a um agente?

Lendo-os em um agendamento. As notificações push do YouTube informam um novo upload, um novo título ou uma nova descrição, não comentários, e o easyCoexistence não recebe eventos de comentários do LinkedIn, então nenhum dos dois encaminha nada. O agente faz a verificação: list_youtube_comments devolve as threads de um vídeo ou de todo o canal, inclusive as retidas para revisão, e list_linkedin_comments devolve os comentários de uma publicação ou as respostas sob um deles. No n8n, Make ou Zapier, um gatilho de agendamento inicia a verificação; no seu próprio código, um cron job busca as credenciais do canal e chama diretamente o endpoint commentThreads do YouTube ou o endpoint de comments do LinkedIn.

Como configurar

  1. 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.
  2. Store the secretSave the signing_secret from the response against that account_id, since it is shown only once.
  3. Verify each deliveryCheck that the timestamp is fresh and that v1 matches an HMAC-SHA256 of the timestamp, a dot and the raw body.
  4. 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á parseado. A assinatura cobre o corpo bruto byte a byte, e serializar de novo o objeto parseado muda esses bytes, então verifique antes de fazer o parse.
  • Usar um único segredo para todas as contas. Cada conta assina com o próprio segredo, então busque-o pelo account_id do evento antes de comparar o v1.
  • Definir o destino de novo sem atualizar o seu endpoint. Cada chamada gera um novo segredo e o antigo deixa de assinar imediatamente, então guarde o novo na hora.
  • Informar uma URL que redireciona. Os encaminhamentos não seguem redirecionamentos, então uma mudança de caminho ou de host perde o evento; defina o endereço final.
Fazendo isso com o EasyCoexistence

O easyCoexistence envia comentários, menções e DMs do Instagram e do Facebook, e comentários do TikTok, para o seu endpoint assim que acontecem, assinados por conta, e direciona as mensagens do WhatsApp ao seu servidor, para que seus agentes de IA recebam mensagens dos seus clientes pela API oficial de cada rede, com cada conexão monitorada 24/7. 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 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

Como as mensagens de um número do WhatsApp chegam ao meu endpoint?

De um de dois modos. set_webhook_destination faz a Meta entregá-las diretamente ao seu servidor, enquanto set_inbound_mode com um forward_url faz o easyCoexistence encaminhá-las assinadas com X-EC-Signature, repetindo com backoff.

O mesmo evento pode chegar duas vezes?

Pode, então deduplique pelos IDs da própria rede, como um ID de comentário ou um message mid. As repetições da Meta de uma entrega do WhatsApp que o seu servidor não aceitou, por até 7 dias, também podem gerar duplicatas.

Um único endpoint pode receber eventos de várias contas?

Sim. Cada evento traz platform e account_id, então uma URL pode atender muitas contas, desde que verifique cada assinatura com o segredo próprio daquela conta.

Quanto custa o easyCoexistence para webhooks de redes sociais?

De US$ 9 a US$ 0.75 por conexão por mês, com redução conforme você adiciona conexões, e o mesmo valor em todas as redes. Encaminhamento, o servidor MCP e a Partner API estão incluídos, com os primeiros 3 dias grátis.

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