Webhooks

✨ Bem-vindo(a) à nossa versão Beta de Webhooks!

Esta funcionalidade está atualmente em Beta, o que significa que ainda estamos a desenvolvendo ativamente. Adicionaremos mais tipos de eventos e funcionalidades com base no seu feedback. Se houver um evento específico que você precisa, por favor, não hesite em entrar em contato com nossa equipe de suporte.

O que são Webhooks?

Webhooks são a forma que a Bolten utiliza para enviar dados em tempo real para suas outras aplicações sempre que um evento específico acontece no seu projeto. Nós enviaremos proativamente uma notificação (um request POST), junto com detalhes e informações, para uma URL que você fornecer.

Isso é ótimo para casos como:

  • Automatizar comunicações por diversos canais quando um lead muda de estágio.

  • Realizar agendamentos em outras plataformas em determinados estágios de um lead.

Quando usar Webhooks vs. nossa API

  • Use Webhooks quando você quiser ser notificado imediatamente sobre um evento que ocorreu na Bolten e/ou tiver um fluxo a ser acionado a partir de algum acontecimento no seu projeto.

  • (Em breve) Use nossa API quando você quiser buscar dados da Bolten de forma proativa ou atualizar informações na Bolten a partir de outro sistema.

Como configurar

Veja como você pode configurar seu primeiro webhook em apenas alguns passos.

1. Acessando os Webhooks

Você pode encontrar as configurações de Webhooks dentro de um projeto na Bolten em Configurações > Integrações > Webhooks.

2. Criando um Novo Webhook

  1. Na página de Webhooks, clique no botão "+ Webhook".

  2. Você verá uma tela de configuração onde precisará preencher alguns detalhes:

    • URL do Endpoint: Esta é a URL da sua aplicação onde você deseja receber os dados do webhook.

    • Nome: Um nome amigável para te ajudar a lembrar para que serve este webhook (ex: "Notificações no Slack para Negócios Ganhos").

    • Eventos: Marque as caixas dos eventos sobre os quais você deseja ser notificado.

Autenticação

Para garantir que seus dados sejam enviados de forma segura, oferecemos algumas maneiras de autenticar seus webhooks.

Unauthenticated (sem autenticação)

Esta opção não adiciona nenhuma segurança às suas requisições de webhook. É útil para testes ou para enviar dados para serviços internos e não críticos.

Basic Auth

Se o seu endpoint é protegido com Autenticação HTTP Básica, enviaremos o seguinte nos headers das requests:

Authorization: Basic <base64(user:password)>

API Key

Nós podemos incluir uma Chave de API (API Key) secreta nos cabeçalhos de cada requisição que enviamos. Este é um método seguro e recomendado. Adicionaremos o seguinte cabeçalho a cada requisição:

X-API-KEY: SUA_CHAVE_SECRETA

Você pode então verificar esta chave no seu servidor para garantir que a requisição está vindo da Bolten.

Bearer Token

Você também pode configurar autenticação via header Bearer:

Authorization: Bearer <token>

Eventos e Payloads

Importante: dentro do campo opportunity, serão enviados todos (e apenas) os campos configurados na oportunidade do seu projeto. O mesmo vale para o contato que estiver vinculado à oportunidade.

Funil

OpportunityWon

Pré-requisito: seu funil precisa ter um status de ganho configurado (no menu Configurações na tela de um funil).

Disparado quando uma oportunidade é movida para o estágio configurado como "ganho".

Observação: além deste evento, também será disparado um opportunity.transitioned.

Exemplo de corpo da requisição:

{
  "id": "d8292e23-b712-4d0c-bf82-1f139d698a20",
  "created_at": "2025-07-24T16:47:24.485-03:00",
  "type": "opportunity.won",
  "data": {
    "opportunity": {
      "id": "536fb699-6381-4723-974d-ccc1d620a72c",
      "component_id": "8cf22145-0380-41f9-a235-1bdefbf22a35",
      "created_at": "2025-07-28T18:21:27.354-03:00",
      "updated_at": "2025-07-28T18:21:27.354-03:00",
      "Name": "Nome do Lead",
      "E-mail": "email.lead@bolten.io",
      "Status": "Done",
      "Contato": {
        "Nome": "Nome do Lead",
        "E-mail": "email.lead@bolten.io",
        "Telefone": "5511999999999"
      },
      "Tarefas": [
        {
          "id": "f6f8fede-5814-49f0-8dc3-810daea7747b",
          "state": "to_do",
          "title": "Tarefa exemplo",
          "created_at": "2025-07-24T11:30:00.541-03:00",
          "updated_at": "2025-07-24T11:30:00.541-03:00",
          "description": "Tarefa de exemplo",
          "scheduled_to": "2023-12-28T00:00:00.000-03:00"
        }
      ],
      "Produtos": [
        {
          "id": "9f435f4a-9f52-420e-a2bf-f7a99a90af77",
          "quantity": 2,
          "product_name": "Produto A",
          "final_price_cents": 24600,
          "product_price_cents": 12300,
          "final_price_currency": "BRL",
          "product_price_currency": "BRL"
        }
      ]
    }
  }
}
OpportunityLost

Pré-requisito: seu funil precisa ter um status de perdido configurado (no menu Configurações na tela de um funil).

Disparado quando uma oportunidade é movida para o estágio configurado como "perdido".

Observação: além deste evento, também será disparado um opportunity.transitioned.

Exemplo de corpo da requisição:

{
  "id": "d8292e23-b712-4d0c-bf82-1f139d698a20",
  "created_at": "2025-07-24T16:47:24.485-03:00",
  "type": "opportunity.lost",
  "data": {
    "opportunity": {
      "id": "536fb699-6381-4723-974d-ccc1d620a72c",
      "component_id": "8cf22145-0380-41f9-a235-1bdefbf22a35",
      "Name": "Nome do Lead",
      "E-mail": "email.lead@bolten.io",
      "Status": "Done",
      "Contato": {
        "Nome": "Nome do Lead",
        "E-mail": "email.lead@bolten.io",
        "Telefone": "5511999999999"
      },
      "Tarefas": [
        {
          "id": "f6f8fede-5814-49f0-8dc3-810daea7747b",
          "state": "to_do",
          "title": "Tarefa exemplo",
          "created_at": "2025-07-24T11:30:00.541-03:00",
          "updated_at": "2025-07-24T11:30:00.541-03:00",
          "description": "Tarefa de exemplo",
          "scheduled_to": "2023-12-28T00:00:00.000-03:00"
        }
      ],
      "Produtos": [
        {
          "id": "9f435f4a-9f52-420e-a2bf-f7a99a90af77",
          "quantity": 2,
          "product_name": "Produto A",
          "final_price_cents": 24600,
          "product_price_cents": 12300,
          "final_price_currency": "BRL",
          "product_price_currency": "BRL"
        }
      ]
    }
  }
}
OpportunityTransitioned

Disparado quando uma oportunidade é movida de um estágio para outro.

Observação: este evento também é emitido quando ocorre um opportunity.won ou opportunity.lost. Além disso, caso a transição seja para um status configurado como ganho ou perdido, os eventos correspondentes também serão disparados.

Exemplo de corpo da requisição:

{
  "id": "d8292e23-b712-4d0c-bf82-1f139d698a20",
  "created_at": "2025-07-24T16:47:24.485-03:00",
  "type": "opportunity.transitioned",
  "data": {
    "from_state": "Doing",
    "to_state": "Done",
    "created_at": "2025-07-28T18:21:27.354-03:00",
    "updated_at": "2025-07-28T18:21:27.354-03:00",
    "opportunity": {
      "id": "536fb699-6381-4723-974d-ccc1d620a72c",
      "component_id": "8cf22145-0380-41f9-a235-1bdefbf22a35",
      "created_at": "2025-07-28T18:21:27.354-03:00",
      "updated_at": "2025-07-28T18:21:27.354-03:00",
      "Name": "Nome do Lead",
      "E-mail": "email.lead@bolten.io",
      "Status": "Done",
      "Contato": {
        "Nome": "Nome do Lead",
        "E-mail": "email.lead@bolten.io",
        "Telefone": "5511999999999"
      },
      "Tarefas": [
        {
          "id": "f6f8fede-5814-49f0-8dc3-810daea7747b",
          "state": "to_do",
          "title": "Tarefa exemplo",
          "created_at": "2025-07-24T11:30:00.541-03:00",
          "updated_at": "2025-07-24T11:30:00.541-03:00",
          "description": "Tarefa de exemplo",
          "scheduled_to": "2023-12-28T00:00:00.000-03:00"
        }
      ],
      "Produtos": [
        {
          "id": "9f435f4a-9f52-420e-a2bf-f7a99a90af77",
          "quantity": 2,
          "product_name": "Produto A",
          "final_price_cents": 24600,
          "product_price_cents": 12300,
          "final_price_currency": "BRL",
          "product_price_currency": "BRL"
        }
      ]
    }
  }
}
OpportunityCreated

Disparado quando uma oportunidade é criada.

Exemplo de corpo da requisição:

{
  "id": "d8292e23-b712-4d0c-bf82-1f139d698a20",
  "created_at": "2025-07-24T16:47:24.485-03:00",
  "type": "opportunity.created",
  "data": {
    "opportunity": {
      "id": "536fb699-6381-4723-974d-ccc1d620a72c",
      "component_id": "8cf22145-0380-41f9-a235-1bdefbf22a35",
      "created_at": "2025-07-28T18:21:27.354-03:00",
      "updated_at": "2025-07-28T18:21:27.354-03:00",
      "Name": "Nome do Lead",
      "E-mail": "email.lead@bolten.io",
      "Status": "Done",
      "Contato": {
        "Nome": "Nome do Lead",
        "E-mail": "email.lead@bolten.io",
        "Telefone": "5511999999999"
      },
      "Produtos": [
        {
          "id": "9f435f4a-9f52-420e-a2bf-f7a99a90af77",
          "quantity": 2,
          "product_name": "Produto A",
          "final_price_cents": 24600,
          "product_price_cents": 12300,
          "final_price_currency": "BRL",
          "product_price_currency": "BRL"
        }
      ]
    }
  }
}

Tratamento de Erros e Retentativas

Como a Bolten Lida com Falhas

Se o seu endpoint não responder com um código de status 2xx (ex: 200 OK), consideraremos a entrega como uma falha. Nós então tentaremos reenviar o webhook mais 5 vezes, com intervalos exponenciais (exponential backoff) entre cada tentativa. Se todas as retentativas falharem, pararemos de enviar aquele evento específico.

Visualizando Entregas

Na página de detalhes do webhook, você pode ver um log das entregas mais recentes. Para fins de solução de problemas, nós exibimos apenas a requisição e resposta mais recente para cada invocação de webhook.

Boas Práticas

Aqui estão algumas dicas para tornar sua integração com webhooks o mais confiável possível:

  • Responda Rapidamente: Receba os webhooks retornando um status 200 OK o mais rápido possível. Evite executar lógicas complexas antes de enviar a resposta. É melhor receber os dados, responder, e então processá-los de forma assíncrona.

  • Lide com Duplicatas: Em casos raros, seu endpoint pode receber o mesmo webhook mais de uma vez. Projete seu sistema para ser idempotente (ou seja, capaz de lidar com eventos duplicados sem causar problemas).

  • Mantenha suas Chaves Seguras: Trate sua API Key como uma senha. Não a exponha no código do lado do cliente (client-side) ou em repositórios públicos.

AnteriorComo escalar seu negócioPróximoAPI

Atualizado