Webhooks: leve cada envio para o seu sistema

EsforçoSem códigoCanalWebhookPlanoGrátis

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.

#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

1. 1Crie o webhook com URL, cabeçalhos e corpo
2. 2Teste com um contato fictício e confira o log
3. 3Anexe 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.

dash.bip.marketing/…/webhooks/…

Captura de tela em breve

#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' }}".

dash.bip.marketing/…/webhooks/…

Captura de tela em breve

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

dash.bip.marketing/…/webhooks/…

Captura de tela em breve

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

dash.bip.marketing/…/webhooks/stats/…

Captura de tela em breve

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

dash.bip.marketing/…/campaigns/…

Captura de tela em breve

#Referência

#Configuração do webhook

#Entrega e novas tentativas

#Variáveis do contato

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

#Variáveis de telefone

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

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

#Variáveis de opt-out

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

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

{
  "Content-Type": "application/json",
  "Authorization": "Bearer SEU_TOKEN_DO_CRM"
}

{
  "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') }}"
}

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

{
  "Content-Type": "application/json"
}

{
  "text": "Novo interessado: {{ lead.name() }} | {{ lead.email() || 'sem e-mail' }} | {{ lead.phone('international') || 'sem telefone' }} | {{ lead.location('last', 'city') || 'cidade não informada' }}"
}

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
• API da BIP: chaves, contatos, eventos e disparos
• Script do site: page views e cliques ligados ao contato
• Conformidade: portal do contato, opt-out e tópicos
• Referência completa da API