# Webhooks: leve cada envio para o seu sistema

> Em Webhooks, crie um webhook com método, URL, cabeçalhos e um corpo JSON com variáveis como {{ lead.name() }}. Teste com um contato fictício, anexe até 3 webhooks a uma campanha de e-mail (ou use só webhooks) e acompanhe cada entrega nos logs. Se o destino falhar, a BIP tenta até 6 vezes, a cada 60 segundos.

Fonte: https://wiki.bip.marketing/pt-br/webhooks · Atualizado: 2026-10-08

<UseCaseMeta effort="nocode" channel="webhook" plan="free" />

Toda vez que uma campanha alcança um contato, a BIP pode avisar outro sistema: criar o contato no CRM, mandar uma mensagem para a equipe, alimentar uma planilha. Você monta o pedido uma vez no painel, com os dados do contato no lugar certo, e a BIP faz o resto a cada envio.

<Checklist items="Uma conta na BIP (vale o plano gratuito)|O endereço (URL) que vai receber os dados e o token de acesso, se o destino pedir|Uma campanha de e-mail, recorrente, única ou por API, para anexar o webhook" />

## O que você vai conseguir

- Cada contato da campanha chega ao seu CRM ou ferramenta, com nome, e-mail, telefone, cidade, campos e KPIs que você escolher.
- Tudo no painel, sem código: método, URL, cabeçalhos e corpo, com sugestões de variáveis e pré-visualização.
- Entregas que se recuperam sozinhas: se o destino falhar, a BIP tenta de novo.
- Logs com a requisição e a resposta de cada entrega, e métricas por webhook.
- Campanhas só com webhooks, para sincronizar sistemas sem mandar e-mail.

## Como funciona

<Steps items="Crie o webhook com URL, cabeçalhos e corpo|Teste com um contato fictício e confira o log|Anexe a uma campanha: cada contato processado dispara o webhook" />

Um webhook é um pedido HTTP que a BIP faz ao seu sistema. Você define o método, a URL, os cabeçalhos e o corpo em JSON. No corpo, variáveis como `{{ lead.name() }}` viram os dados de cada contato na hora do envio.

O webhook roda quando está anexado a uma campanha. A cada contato que a campanha processa, a BIP monta o corpo com os dados daquela pessoa e envia. Vale para campanhas **Único**, **Recorrente** e **Disparo por API**. Quem saiu de todas as comunicações não dispara o webhook.

A entrega é bem-sucedida quando o seu sistema responde com um código 2xx (200, 201, 204…). Qualquer outra resposta, ou nenhuma resposta, gera uma nova tentativa 60 segundos depois. São até 6 tentativas no total: a primeira e mais 5.

## Passo a passo

### 1. Crie o webhook

1. No menu, abra **Webhooks** e clique em **Novo Webhook**. A BIP cria um webhook **[sem título]** e abre a página dele.
2. Em **Configuração de Webhook**, escolha o método. Para levar os dados do contato, use **POST** (ou **PUT**, se o destino pedir).
3. Cole a URL que vai receber os dados, no lugar de `http://your-webhook-endpoint.com`.
4. Clique em **Salvar**.

<Shot src="/img/webhooks/1-pt-br.png" alt="Página do webhook com método e URL em Configuração de Webhook" url="dash.bip.marketing/…/webhooks/…" />

### 2. Monte os cabeçalhos e o corpo

1. Abra **Cabeçalhos** e escreva um objeto JSON. Inclua sempre `"Content-Type": "application/json"`: a BIP envia o corpo como JSON e a maioria dos sistemas confere esse cabeçalho. Se o destino pede um token, coloque também, por exemplo `"Authorization": "Bearer SEU_TOKEN"`.
2. Em **Modelo do Corpo**, escreva o JSON que o destino espera. Dentro de um valor entre aspas, digite `{{` e escolha a variável na lista de sugestões. O ícone de ajuda ao lado de **Modelo do Corpo** mostra todas as variáveis.
3. Confira a **Pré-visualização** à direita: ela mostra o corpo pronto, com os dados de um contato fictício, e se atualiza logo depois que você para de digitar.
4. Clique em **Salvar**.

O corpo precisa ser um JSON válido para salvar. Por isso, cada variável fica entre aspas e chega ao destino como texto: `"vip": "{{ lead.hasTag('vip') }}"` vira `"vip": "true"`.

Para um valor reserva quando o dado está vazio, use `||`: `"saudacao": "Olá, {{ lead.firstName() || 'cliente' }}"`.

<Shot src="/img/webhooks/2-pt-br.png" alt="Cabeçalhos, modelo do corpo com variáveis e pré-visualização do webhook" url="dash.bip.marketing/…/webhooks/…" />

<Callout type="tip">
Para campos personalizados, KPIs e tags, escolha sempre pela lista de sugestões. A lista mostra o nome que você conhece e grava o identificador interno que a BIP usa para achar o dado.
</Callout>

### 3. Dê um nome e organize

1. No topo da página, clique em **Configurações**.
2. Preencha o **Nome** (é o que aparece ao anexar em campanhas), escolha um ícone e, se quiser, uma **Descrição**.
3. Em **Grupo**, escolha um grupo para organizar a lista. Os grupos de webhooks são criados em **Configurações** → **Grupos**.
4. Em **Status**, deixe **Ativo** ligado.
5. Clique em **Salvar**.

<Shot src="/img/webhooks/3-pt-br.png" alt="Configurações do webhook com nome, ícone, descrição, grupo e status" url="dash.bip.marketing/…/webhooks/…" />

### 4. Teste com um contato fictício

1. Com tudo salvo, clique em **Testar Webhook**. O botão fica disponível quando não há alterações por salvar.
2. A BIP envia uma requisição real para a sua URL, com um contato fictício (nome, e-mail, telefone e cidades inventados; campos personalizados vazios), e abre **Estatísticas do Webhook**.
3. Em **Logs de Entrega**, clique em **Visualizar** na linha do teste. **Requisição** mostra o que a BIP enviou; **Resposta** mostra o código e o corpo que o seu sistema devolveu.

O teste chega ao seu sistema de verdade. Se o destino for o CRM em produção, apague o registro de teste depois, ou aponte primeiro para um ambiente de testes.

<Shot src="/img/webhooks/4-pt-br.png" alt="Estatísticas do webhook com o log de entrega do teste" url="dash.bip.marketing/…/webhooks/stats/…" />

### 5. Anexe a uma campanha

1. Em **Campanhas**, abra uma campanha ou clique em **Nova Campanha**, com o **Canal** **Email**.
2. Na seção **Webhooks**, selecione até 3 webhooks. Cada contato processado dispara todos eles.
3. Para uma campanha **só com webhooks**, não escolha **Modelo de E-mail** e selecione pelo menos um webhook. Nenhum e-mail sai: cada contato só dispara os webhooks.
4. Escolha o **Tipo de Agendamento** (**Único**, **Recorrente** ou **Disparo por API**), salve e ative como qualquer campanha.

<Shot src="/img/webhooks/5-pt-br.png" alt="Seção Webhooks de uma campanha de e-mail com webhooks selecionados" url="dash.bip.marketing/…/campaigns/…" />

<PlanOnly plan="full">
Nos **Fluxos**, o passo **Enviar Webhook** usa os mesmos webhooks: o contato dispara o webhook quando chega naquele ponto do fluxo.
</PlanOnly>

## Referência

### Configuração do webhook

| Opção           | Como funciona                                                          |
| --------------- | ---------------------------------------------------------------------- |
| Método          | GET, POST, PUT ou DELETE. Para enviar dados no corpo, use POST ou PUT. |
| URL             | Endereço de destino. Fixo: não aceita variáveis.                       |
| Cabeçalhos      | Objeto JSON, como `{"Content-Type": "application/json"}`. Fixos.       |
| Modelo do Corpo | JSON válido, com variáveis do contato entre aspas.                     |
| Nome, ícone     | Como o webhook aparece na lista e nas campanhas.                       |
| Descrição       | Texto livre, para a equipe.                                            |
| Grupo           | Organiza a lista de **Webhooks**.                                      |
| Status          | **Ativo** ou inativo.                                                  |

### Entrega e novas tentativas

| Regra                 | Valor                                                      |
| --------------------- | ---------------------------------------------------------- |
| Sucesso               | Resposta com código 2xx                                    |
| Nova tentativa        | Qualquer outro código, ou sem resposta                     |
| Intervalo             | 60 segundos                                                |
| Tentativas no total   | 6 (a primeira e mais 5)                                    |
| Depois da 6ª falha    | A campanha registra um erro de webhook para aquele contato |
| Webhooks por campanha | Até 3, em campanhas do canal Email, com ou sem e-mail      |

### Variáveis do contato

Use dentro de um valor entre aspas. O resultado chega como texto.

| Variável                                | O que traz                                           |
| --------------------------------------- | ---------------------------------------------------- |
| `{{ lead.name() }}`                     | Nome completo                                        |
| `{{ lead.firstName() }}`                | Primeiro nome                                        |
| `{{ lead.middleName() }}`               | Nomes do meio                                        |
| `{{ lead.lastName() }}`                 | Sobrenome                                            |
| `{{ lead.email() }}`                    | E-mail                                               |
| `{{ lead.id() }}`                       | ID do contato na BIP                                 |
| `{{ lead.namespace() }}`                | Namespace da conta                                   |
| `{{ lead.createdAt() }}`                | Data de criação, no formato ISO 8601                 |
| `{{ lead.createdAt('YYYY-MM-DD') }}`    | Data de criação formatada                            |
| `{{ lead.updatedAt() }}`                | Última atualização, no formato ISO 8601              |
| `{{ lead.updatedAt('YYYY-MM-DD') }}`    | Última atualização formatada                         |
| `{{ lead.metadata('[METADATA_KEY]') }}` | Um metadado: troque `[METADATA_KEY]` pela chave      |
| `{{ lead.sourceType('first') }}`        | Tipo da primeira origem (`api`, `internal`, `page`…) |
| `{{ lead.sourceType('last') }}`         | Tipo da última origem                                |

### Variáveis de telefone

| Variável                                           | Exemplo                              |
| -------------------------------------------------- | ------------------------------------ |
| `{{ lead.phone('e164') }}`                         | `+5511912345678`                     |
| `{{ lead.phone('international') }}`                | `+55 11 91234-5678`                  |
| `{{ lead.phone('national') }}`                     | `(11) 91234-5678`                    |
| `{{ lead.phone('nationalNumber') }}`               | `11912345678`                        |
| `{{ lead.phone('countryCallingCode') }}`           | `55`                                 |
| `{{ lead.phone('countryCode') }}`                  | `BR`                                 |
| `{{ lead.phone('numberType') }}`                   | `MOBILE`                             |
| `{{ lead.phone('uri') }}`                          | `tel:+5511912345678`                 |
| `{{ lead.maskedPhone('e164', '(999) 999-9999') }}` | Telefone na máscara que você definir |

Na máscara, cada `9` é um dígito, preenchido da esquerda para a direita. Para o formato brasileiro, use `{{ lead.maskedPhone('national', '(99) 99999-9999') }}`.

### Variáveis de localização

| Variável                                   | O que traz                             |
| ------------------------------------------ | -------------------------------------- |
| `{{ lead.location('last', 'city') }}`      | Cidade da última localização           |
| `{{ lead.location('last', 'region') }}`    | Estado ou região da última localização |
| `{{ lead.location('last', 'country') }}`   | País da última localização             |
| `{{ lead.location('last', 'timezone') }}`  | Fuso horário da última localização     |
| `{{ lead.location('last', 'latitude') }}`  | Latitude do centro da cidade           |
| `{{ lead.location('last', 'longitude') }}` | Longitude do centro da cidade          |

Troque `last` por `first` para a primeira localização. A localização é sempre a da cidade.

### Variáveis de opt-out

| Variável                                         | O que traz                                       |
| ------------------------------------------------ | ------------------------------------------------ |
| `{{ lead.unsubscribed() }}`                      | `true` se a pessoa saiu de todas as comunicações |
| `{{ lead.unsubscribedFromChannel('email') }}`    | `true` se saiu do e-mail                         |
| `{{ lead.unsubscribedFromChannel('whatsapp') }}` | `true` se saiu do WhatsApp                       |

### Variáveis da sua conta

O editor cria estas variáveis a partir dos seus campos personalizados, KPIs e tags. Na lista de sugestões, elas aparecem com o nome que você deu.

| Variável                                                                 | Para                                                                                |
| ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
| `{{ lead.field('Nome do campo') }}`                                      | Campos String, Número, Booleano e Data                                              |
| `{{ lead.dateField('Nome do campo', 'YYYY-MM-DD') }}`                    | Campo Data, no formato que você escolher                                            |
| `{{ lead.ageField('Nome do campo') }}`                                   | Idade em anos, a partir de um campo Data                                            |
| `{{ lead.locationField('Nome do campo', 'city') }}`                      | Campo Localização (também `region`, `country`, `timezone`, `latitude`, `longitude`) |
| `{{ lead.phoneField('Nome do campo', 'e164') }}`                         | Campo Telefone (também os formatos da tabela de telefone)                           |
| `{{ lead.maskedPhoneField('Nome do campo', 'e164', '(999) 999-9999') }}` | Campo Telefone com máscara                                                          |
| `{{ lead.maskedNumberField('Nome do campo', '999 999 999 99') }}`        | Campo Número com máscara                                                            |
| `{{ lead.kpi('Nome do KPI') }}`                                          | Valor de um KPI                                                                     |
| `{{ lead.hasTag('Nome da tag') }}`                                       | `true` se o contato tem a tag                                                       |

## Pronto para copiar

### Enviar cada contato para um CRM

A Agência Pulso manda para o CRM cada pessoa que recebe a campanha de boas-vindas. Ajuste os nomes das chaves ao que o seu CRM espera.

<Copy label="Cabeçalhos" code>
{
  "Content-Type": "application/json",
  "Authorization": "Bearer SEU_TOKEN_DO_CRM"
}
</Copy>

<Copy label="Modelo do Corpo" code>
{
  "nome": "{{ lead.name() }}",
  "email": "{{ lead.email() }}",
  "telefone": "{{ lead.phone('e164') }}",
  "cidade": "{{ lead.location('last', 'city') }}",
  "estado": "{{ lead.location('last', 'region') }}",
  "origem": "bip",
  "id_bip": "{{ lead.id() }}",
  "criado_em": "{{ lead.createdAt('YYYY-MM-DD') }}"
}
</Copy>

| Configuração | Valor                                            |
| ------------ | ------------------------------------------------ |
| Método       | POST                                             |
| URL          | O endereço de criação de contatos do seu CRM     |
| Campanha     | Canal **Email**, com ou sem **Modelo de E-mail** |
| Webhooks     | Este webhook (até 3 por campanha)                |

Para mandar ao CRM cada pessoa no momento do cadastro, sem e-mail: crie uma campanha só com este webhook, com **Disparo por API** em modo **Imediato**, e dispare pela [API](/pt-br/api) quando alguém se cadastrar.

### Avisar a equipe

Muitas ferramentas de chat e de automação recebem mensagens por um webhook de entrada, com o texto no campo `text`. A Imobiliária Marés avisa os corretores a cada pessoa que entra na campanha de lançamento.

<Copy label="Cabeçalhos" code>
{
  "Content-Type": "application/json"
}
</Copy>

<Copy label="Modelo do Corpo" code>
{
  "text": "Novo interessado: {{ lead.name() }} | {{ lead.email() || 'sem e-mail' }} | {{ lead.phone('international') || 'sem telefone' }} | {{ lead.location('last', 'city') || 'cidade não informada' }}"
}
</Copy>

Confira na ferramenta de destino o nome do campo de texto que ela espera e troque `text`, se for o caso.

## Como medir

- **Estatísticas do Webhook**: na lista de **Webhooks**, abra o webhook e clique em **Ver Estatísticas**. Você vê **Total de Requisições**, **Bem-sucedido**, **Falhou**, **Tempo Médio de Resposta**, **Taxa de Sucesso**, **Taxa de Retentativa**, **Taxa de Erro**, **Códigos de Status** e o **Detalhamento de Entregas**. Os números atualizam **Ao vivo**.
- **Logs de Entrega**: filtre por **Data Inicial**, **Data Final** e **Limite**. Cada linha traz **Data**, **Status**, **URL**, **Método** e **Tentativas**; em **Visualizar**, você confere a **Requisição** e a **Resposta** completas.
- **Na campanha**: em **Ver Estatísticas**, **Entrega de Webhook** e **Erros de Webhook** mostram o total da campanha, e **Interações do Destinatário** mostra o webhook de cada contato.
- Uma **Taxa de Retentativa** alta indica que o destino está lento ou instável. Abra a **Resposta** nos logs para ver o motivo.

## Perguntas frequentes

### O que conta como entrega bem-sucedida?

Uma resposta com código 2xx. Qualquer outro código, ou nenhuma resposta, gera nova tentativa 60 segundos depois, até 6 tentativas no total. Depois da sexta falha, a campanha registra o erro daquele contato.

### Webhook conta como envio?

Numa campanha de e-mail com webhooks, conta o envio daquele contato, uma vez só: os webhooks não somam. Numa campanha só com webhooks, cada contato processado conta como um envio, como se fosse um e-mail. O **Testar Webhook** não conta.

### Posso usar variáveis na URL ou nos cabeçalhos?

Não. A URL e os cabeçalhos são fixos. As variáveis do contato funcionam no **Modelo do Corpo**.

### O teste chega ao meu sistema?

Sim. O **Testar Webhook** faz uma requisição real, com um contato fictício. Use um ambiente de testes ou apague o registro depois.

## Veja também

- [Campanhas: única, recorrente e por API](/pt-br/campanhas)
- [API da BIP: chaves, contatos, eventos e disparos](/pt-br/api)
- [Script do site: page views e cliques ligados ao contato](/pt-br/script-do-site)
- [Conformidade: portal do contato, opt-out e tópicos](/pt-br/conformidade)
- [Referência completa da API](https://bipmarketing.readme.io)