Webhook para Zapier e Make

Por que webhook, e não um app pronto no Zapier

Até abril de 2024, havia um caminho oficial: a Facebook Groups API, na qual se baseavam o gatilho “New Post in Group” no Zapier e o módulo correspondente no Make. A Meta a desativou e não colocou nada no lugar. O app do Facebook no Zapier ainda existe, mas atende páginas e anúncios — os grupos desapareceram da lista de gatilhos e não voltarão, pois não há mais uma interface em que possam funcionar.

O LeadScanner lê grupos públicos e fanpages sem conta, como um visitante sem login os vê, e após cada varredura pode enviar um evento ao endereço indicado. Para o Zapier e o Make, é um webhook de entrada comum — ou seja, exatamente o gatilho que falta. Depois disso, há tudo o que essas ferramentas fazem bem: uma linha na planilha, um cartão no CRM, uma mensagem no Slack, uma tarefa para o vendedor.

O canal de webhook está disponível no plano Growth e superiores. Ele é configurado pelo proprietário ou administrador da organização, no painel, em Notificações → Canais.

Configuração no Zapier

No Zapier, crie um novo Zap e selecione como gatilho o app “Webhooks by Zapier”, evento “Catch Hook”. O Zapier mostrará o endereço em que está aguardando — copie-o. Não feche esta aba; você voltará a ela em breve.

No painel do LeadScanner, abra Notificações → Canais e adicione um canal Webhook. Cole o endereço copiado. Se quiser que o outro lado diferencie seus eventos dos demais, adicione um cabeçalho de autenticação: um nome (por exemplo, X-Api-Key) e um valor criado por você. Isso é opcional, mas barato, e vale a pena fazer logo.

Selecione os eventos que devem ser enviados: “Novos leads”, “Varredura concluída” ou ambos. Para automação de vendas, geralmente basta o primeiro; o segundo é útil quando você quer registrar cada varredura, inclusive as vazias. Salve o canal e clique em “Enviar teste”.

Volte ao Zapier e clique em “Test trigger”. O Zapier receberá o evento de teste e o dividirá em campos que, a partir de agora, você pode mapear nas próximas etapas: person_name para a coluna com o nome, post_url para o link, score para a prioridade. O evento de teste tem o campo test definido como true e dados de exemplo — não adicione essa pessoa ao CRM, pois ela não existe.

Configuração no Make

No Make, adicione ao cenário o módulo “Webhooks” → “Custom webhook”, dê um nome a ele e copie o endereço gerado. A partir de agora, o Make fica aguardando a primeira mensagem para ler dela a estrutura dos dados.

As etapas no painel do LeadScanner são as mesmas do Zapier: Notificações → Canais → Webhook, cole o endereço, adicione opcionalmente um cabeçalho de autenticação, selecione os eventos, salve e clique em “Enviar teste”.

Após o teste, o Make mostrará que reconheceu a estrutura. Se você não vir isso — por exemplo, porque o webhook já estava aguardando antes e memorizou outro formato — clique no módulo em “Redetermine data structure” e envie o teste mais uma vez. A partir de agora, os campos da carga estão disponíveis em todos os módulos seguintes do cenário.

Uma observação prática para ambas as ferramentas: o evento “Novos leads” traz uma lista, não um único lead. No Make, divida-a com um iterador; no Zapier, use a etapa “Looping by Zapier” — ou mapeie apenas o primeiro item, se você já reage ao pacote inteiro de uma vez.

Evento new_leads: o que chega

Cada evento é uma solicitação POST com corpo no formato JSON. No nível superior, há sempre o mesmo conjunto de campos: event — nome do evento, aqui new_leads; version — número da versão do formato, hoje 1; organization_id — identificador da sua organização; sent_at — hora de envio em ISO 8601; subject — título de uma frase, o mesmo que vai no assunto do e-mail; leads_count — número de leads no pacote; leads — lista de leads.

Cada item da lista leads contém: person_name — nome e sobrenome do autor da publicação, como aparece no Facebook; score — avaliação de 0 a 100; quanto maior, mais certa a consulta; excerpt — trecho da publicação ou comentário em que a pergunta apareceu; post_url — link para a publicação; profile_url — link para o perfil do autor, se estava visível; caso contrário, null; rationale — uma frase sobre por que essa publicação foi considerada um lead; source_name — nome do grupo ou página em que apareceu.

O envio de teste tem exatamente esse formato, apenas com dados de exemplo e o campo adicional test definido como true. É a forma mais simples de ver um exemplo completo: clique em “Enviar teste” e veja no Zapier ou no Make o que chegou.

Evento scan_finished: o mesmo, mais a varredura

O evento scan_finished inclui todos os campos descritos acima — com a lista de leads encontrados nesta varredura, que pode estar vazia — e, além disso, o objeto scan. Nele: id — identificador da varredura; source_id, source_name e source_url — qual fonte foi verificada; status — como terminou; mode — modo, palavras-chave ou IA; scheduled_slot — slot do agendamento ao qual a varredura pertencia; started_at e finished_at — horário de início e término; points_spent — quantos pontos custou; leads_found — quantos leads encontrou; error e error_code — descrição e código do erro, quando a varredura falhou; caso contrário, null.

Além disso, coverage, ou seja, o detalhamento do que a varredura analisou: posts_seen e comments_seen — quantas publicações e comentários leu; posts_suppressed — quantas publicações ignorou porque seus autores pediram a remoção dos dados; posts_stale e comments_stale — quantos eram mais antigos que a janela de atualização; posts_unchanged e comments_unchanged — quantos já conhecia da execução anterior e não avaliou novamente; graded — quantos trechos foram avaliados; leads — quantos deles se tornaram leads; rejected — lista de pares reason e count, ou seja, por quais motivos e quantos foram descartados.

Os números em coverage sempre fecham: graded são as publicações e comentários recentes após subtrair os antigos e os já conhecidos, e leads mais a soma de rejected resulta em graded. Se você criar um dashboard com isso, pode confiar nessas duas identidades.

Os motivos em rejected vêm sempre da mesma lista: no_keyword (nenhuma palavra-chave foi mencionada), no_intent (não é possível determinar se o autor procura algo), not_in_market (fala a linguagem do setor, mas não compra — aconselha, relata, vende), outside_offer (compra, mas não o que você oferece ou não onde você atua), excluded (pergunta exatamente sobre o que você não faz), below_threshold (se encaixa, mas não o suficiente para o limite), ungraded (o modelo respondeu em um formato que não foi possível ler). Mantenha-os como um dicionário, sem mapeá-los por suposição.

Assinatura HMAC e o que usar no lugar dela

Se você definir um segredo no canal, cada solicitação receberá dois cabeçalhos: X-LeadScanner-Timestamp com o horário da assinatura em segundos Unix e X-LeadScanner-Signature com o valor v1=<hex>, em que hex é o HMAC-SHA256 da string “<timestamp>.<ciało>”, calculado com seu segredo. O destinatário calcula o mesmo do seu lado e compara; rejeita assinaturas com mais de cinco minutos. Assim, ninguém que conheça apenas o endereço poderá se passar pelo LeadScanner nem reproduzir uma solicitação capturada uma semana depois.

Sem segredo, não há cabeçalhos de assinatura — o evento é enviado sem assinatura, como na maioria das integrações no-code. Zapier e Make não calculam HMAC sem uma etapa adicional de código, então, para eles, uma proteção mais simples e suficiente é o cabeçalho de autenticação do painel: no lado da automação, adicione um filtro que permita apenas solicitações com esse nome e esse valor.

Há duas regras que não podem ser desativadas: o endereço deve ser HTTPS público — http comum e endereço em rede local não passam — e redirecionamentos são rejeitados. Se seu servidor responder 301 ou 302, a entrega termina com erro, em vez de seguir silenciosamente para outro endereço, pois nesse outro endereço a assinatura e o cabeçalho de autenticação chegariam onde não deveriam.

Quando a entrega falha

Uma resposta diferente de 2xx, tempo esgotado ou conexão interrompida significam uma tentativa malsucedida. Não paramos por aí: enviamos o evento novamente três vezes, com intervalos crescentes — a primeira repetição após meio minuto, a última após alguns minutos. Isso basta para aguardar a reinicialização do servidor ou um limite temporário no Zapier e, ao mesmo tempo, a notificação que finalmente chegar ainda será uma notificação, não um histórico.

Cada tentativa — bem-sucedida ou não — fica visível no painel, no canal, com horário, código de resposta e motivo do erro. Se o evento não chegar após quatro tentativas, ele permanece nessa lista como malsucedido, e é ali que você deve começar a procurar: geralmente é um endereço do Zap que deixou de existir ou um cenário no Make que alguém desativou.