Iniciar sessãoIniciar teste gratuito
easyCoexistence APIs oficiais

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
Começar período experimental gratuito

Nada é cobrado durante 3 dias. Cancele quando quiser.

Apenas APIs oficiaisMCP para Claude e ChatGPTTodas as ligações monitorizadas 24/73 dias grátis
1 attempt

Quantas vezes a easyCoexistence envia cada evento social reencaminhado; não guarda cópia, por isso nada é reenviado mais tarde.

Within 5 minutes

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.

In comments

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.

3 events

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

7 days

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 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 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:

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 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: 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 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

  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á 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.
Fazer isto com a EasyCoexistence

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