Pular para o conteúdo
Rex, seu assistente de IA: o trabalho braçal fica com ele, as ideias ficam com você 👉 Conheça o Rex

Envie dados para seus sistemas com webhooks

Receba uma requisição na sua própria URL quando alguém se cadastrar, participar ou ganhar, com payload assinado, autenticação básica, payload personalizado e registro de cada entrega.

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

  1. Abra a campanha no editor e vá em Conectar > Webhooks.
  2. Clique em Adicionar webhook.
  3. 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.”
  4. Escolha o Tipo de conteúdo: application/json ou application/x-www-form-urlencoded.
  5. 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.
  6. 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.
  7. Informe um Segredo para assinar as requisições (recomendado). Veja “Verifique a assinatura” abaixo.
  8. Ative Registrar corpo da resposta se quiser ver o que seu sistema responde. “Ative para armazenar o corpo da resposta para depuração.”
  9. Mantenha Ativo ligado. “Só entregaremos eventos se o webhook estiver ativo.”
  10. Escolha o evento: “Toda vez que um lead participa de uma campanha” ou “Quando um lead ganha um prêmio”.
  11. Ative Payload personalizado se quiser definir os campos você mesmo (veja abaixo).
  12. 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

  1. 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).
  2. 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.”
  3. Preencha URL do payload, Tipo de conteúdo (“Selecione o tipo de conteúdo do webhook”), Método e Segredo como acima.
  4. Em Quais eventos devem disparar o webhook?, escolha “Quando um novo lead é criado”.
  5. Marque “Sim, quero especificar um payload personalizado (somente usuários avançados)” se quiser seus próprios campos.
  6. 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”).
  7. 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: o id e o name da campanha (webhooks de campanha)
  • lead: os campos do formulário do lead pela chave do campo (por exemplo, first_name), além de id, phone_number e created_at
  • lead.permissions: para cada caixa de consentimento, se foi aceita, o texto, a data e o endereço IP (webhooks de campanha)
  • participant: o channel de 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: o id, name, value, coupon_code do 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.

  1. Em Mapeamento de dados, clique em Adicionar mapeamento.
  2. Digite o Nome do campo que seu sistema espera. Use letras, números, hífens e sublinhados.
  3. Escolha o campo do Scratcher a ser enviado (“Grupo → Campo”), ou Valor personalizado e digite um Valor fixo.
  4. 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.
Precisa de ajuda?

Ainda precisa de ajuda?

Pessoas de verdade estão aqui para ajudar. Se você já usa o Scratcher, o jeito mais rápido é o chat dentro da plataforma.

  • Converse com a gente

    Entre na sua conta e clique no botão de chat no canto inferior direito. O Rex responde na hora, e nossa equipe está a um clique.

  • Agende uma reunião

    Uma videochamada gratuita de 30 minutos com nossa equipe: um tour, ideias de campanhas ou ajuda com a configuração.

  • Mande um e-mail

    Escreva para contact@scratcher.io e retornaremos o contato.