---
title: "Envie dados para seus sistemas com webhooks"
description: "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."
url: https://scratcher.io/pt-br/help/developers/webhooks
language: pt-BR
---

1. [Central de ajuda](https://scratcher.io/pt-br/help)
2. [API, webhooks e MCP](https://scratcher.io/pt-br/help/developers)
3. Envie dados para seus sistemas com webhooks

# 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.

API, webhooks e MCP

- [Comece a usar a API REST](https://scratcher.io/pt-br/help/developers/rest-api)
- [Envie dados para seus sistemas com webhooks](https://scratcher.io/pt-br/help/developers/webhooks)
- [Scratcher MCP para as suas próprias ferramentas de IA](https://scratcher.io/pt-br/help/developers/mcp)

Continue aprendendo

## Artigos relacionados

- [Comece a usar a API REST](https://scratcher.io/pt-br/help/developers/rest-api): Crie um token de acesso pessoal com os escopos certos, ou registre um app OAuth, e leia campanhas, leads e listas a partir dos seus próprios sistemas.
- [Verifique o status de envio e reenvie leads](https://scratcher.io/pt-br/help/integrations/delivery-status): Veja quais leads foram enviados para suas ferramentas, entenda as mensagens de erro, corrija o problema e envie-os novamente.
- [Conecte mais de 8.000 apps com o Zapier](https://scratcher.io/pt-br/help/integrations/zapier): Envie novos cadastros do Scratcher para o Google Sheets, o Slack, seu CRM ou milhares de outros apps com o Zapier.

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](https://platform.scratcher.io/pt-BR/login)**

    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](https://scratcher.io/pt-br/book-a-meeting)**

    Uma videochamada gratuita de 30 minutos com nossa equipe: um tour, ideias de campanhas ou ajuda com a configuração.
- **[Mande um e-mail](mailto:contact@scratcher.io)**

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