Um webhook envia dados para uma URL escolhida por você no momento em que algo acontece, por exemplo, quando alguém participa de uma campanha ou ganha um prêmio. Seu desenvolvedor configura o sistema que recebe esses dados.
Os webhooks fazem parte dos planos que incluem Webhooks & API (Basic e superiores).
Webhooks de campanha ou webhooks de conta?
- Webhooks de campanha são configurados no editor da campanha e disparam apenas para aquela campanha. Eles têm os eventos “Toda vez que um lead participa de uma campanha” e “Quando um lead ganha um prêmio”, além de mais opções.
- Webhooks de conta são configurados em Configurações > Webhooks. Eles têm o evento “Quando um novo lead é criado”: dispara uma vez por pessoa, na primeira vez que ela é adicionada aos seus leads, independentemente da campanha de origem.
Adicione um webhook a uma campanha
- Abra a campanha no editor e vá em Conectar > Webhooks.
- Clique em Adicionar webhook.
- Informe a URL do payload. Ela deve começar com https: “Só oferecemos suporte a webhooks via HTTPS para garantir que os dados enviados permaneçam seguros.”
- Escolha o Tipo de conteúdo: application/json ou application/x-www-form-urlencoded.
- Escolha o Método. O formulário começa em GET, que envia os dados na URL. Escolha POST para enviá-los no corpo, que é o que a maioria dos sistemas espera.
- Em Autenticação (apenas para POST), escolha Basic Auth se sua URL exigir usuário e senha, e preencha Usuário e Senha. Caso contrário, mantenha Nenhuma.
- Informe um Segredo para assinar as requisições (recomendado). Veja “Verifique a assinatura” abaixo.
- Ative Registrar corpo da resposta se quiser ver o que seu sistema responde. “Ative para armazenar o corpo da resposta para depuração.”
- Mantenha Ativo ligado. “Só entregaremos eventos se o webhook estiver ativo.”
- Escolha o evento: “Toda vez que um lead participa de uma campanha” ou “Quando um lead ganha um prêmio”.
- Ative Payload personalizado se quiser definir os campos você mesmo (veja abaixo).
- Clique em Adicionar webhook. Você verá “Webhook adicionado”.
O painel Webhooks lista os webhooks da campanha com Ativo ou Inativo, e Última entrega falhou se a requisição mais recente falhou. Use Ações para Editar, Ver entregas ou Excluir um webhook. Ao editar um webhook, deixe Segredo em branco para manter o atual.
Adicione um webhook de conta
- Vá em Configurações > Webhooks (em Desenvolvedores). Seus webhooks aparecem em Meus webhooks (ou sob o nome de cada lista de leads, se você tiver várias).
- Clique no card com o sinal de mais para adicionar um webhook. A janela Adicionar webhook diz “Envie uma requisição para uma URL externa sempre que os eventos selecionados acontecerem.”
- Preencha URL do payload, Tipo de conteúdo (“Selecione o tipo de conteúdo do webhook”), Método e Segredo como acima.
- Em Quais eventos devem disparar o webhook?, escolha “Quando um novo lead é criado”.
- Marque “Sim, quero especificar um payload personalizado (somente usuários avançados)” se quiser seus próprios campos.
- Marque Registrar corpo da resposta (“Este webhook registrará o corpo da resposta”) se necessário, e mantenha Ativo marcado (“Entregaremos os detalhes do evento quando este hook for disparado”).
- Clique em Adicionar webhook.
Clique em um webhook para alterá-lo (Salvar alterações), definir um Novo segredo, abrir Mostrar entregas ou Excluir webhook (“Esta ação não pode ser desfeita!”).
O que é enviado
Por padrão, o corpo contém um event (o nome do evento: lead_created_on_campaign, new_campaign_winner ou lead_created) e um objeto data:
campaign: oide onameda campanha (webhooks de campanha)lead: os campos do formulário do lead pela chave do campo (por exemplo,first_name), além deid,phone_numberecreated_atlead.permissions: para cada caixa de consentimento, se foi aceita, o texto, a data e o endereço IP (webhooks de campanha)participant: ochannelde onde a pessoa veio e quando participou (webhooks de campanha)quiz: as respostas às perguntas nomeadas do quiz, também sob nomes legíveis que começam com “Simple”prize: oid,name,value,coupon_codedo prêmio e quando foi ganho (webhooks de ganhadores)
Valores vazios são omitidos, assim como consentimentos não aceitos. Com o método GET, os mesmos dados são enviados como parâmetros de consulta na URL.
Payload personalizado
Com Payload personalizado ativado, apenas os campos escolhidos por você são enviados, e não há o invólucro event.
- Em Mapeamento de dados, clique em Adicionar mapeamento.
- Digite o Nome do campo que seu sistema espera. Use letras, números, hífens e sublinhados.
- Escolha o campo do Scratcher a ser enviado (“Grupo → Campo”), ou Valor personalizado e digite um Valor fixo.
- Repita para cada campo. Remova um campo com a lixeira (Remover ou Remover mapeamento de dados).
Verifique a assinatura
Se você definir um segredo, toda requisição terá o cabeçalho X-Hub-Signature: sha1= seguido de um hash HMAC-SHA1 do payload codificado em JSON (o corpo descrito acima), usando seu segredo como chave. Calcule o mesmo do seu lado e compare, para ter certeza de que a requisição veio do Scratcher.
Entregas e novas tentativas
- Se sua URL não responder ou retornar um erro (status 400 ou superior), o Scratcher tenta novamente duas vezes: após 5 segundos e após um minuto.
- Redirecionamentos não são seguidos, então use a URL final.
- Abra as entregas (Ver entregas na campanha, Mostrar entregas para webhooks de conta) para ver cada requisição e resposta. Cada entrega mostra seu ID, a Requisição e a Resposta com o código de status (e o Corpo da resposta, se você o registrar). Use copiar para copiar um payload.
- Ative Mostrar apenas entregas com falha para ver só os problemas. O topo mostra “Entregas com falha nos últimos 60 dias”.
- Clique em Tentar novamente para reenviar uma entrega: “O webhook está sendo reenviado.”
- “Os registros de entrega de webhooks são mantidos por 60 dias.”
Solução de problemas
- “O campo ... deve usar HTTPS.”: a URL do payload começa com http. Use https.
- Todas as entregas falham sem resposta: a URL não pode ser acessada pela internet, por exemplo, um endereço local ou interno. Use uma URL pública.
- Seu sistema não recebe dados: o método é GET, então os dados estão na URL. Mude para POST.
- Falta um campo que seu sistema espera: ele estava vazio ou o consentimento não foi aceito. Faça seu sistema tratar campos ausentes como vazios.