# 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](mailto:suporte@bolten.com). #### 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 {% columns %} {% column width="58.333333333333336%" %} Você pode encontrar as configurações de Webhooks dentro de um projeto na Bolten em **Configurações > Integrações > Webhooks**. {% endcolumn %} {% column %}
{% endcolumn %} {% endcolumns %} #### 2. Criando um Novo Webhook {% columns %} {% column width="41.66666666666667%" %} 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. {% endcolumn %} {% column %}
{% endcolumn %} {% endcolumns %} *** #### 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 ` #### **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 ` *** #### 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 {% hint style="info" %} Pré-requisito: seu funil precisa ter um status de \*\*\*ganho\*\*\* configurado (no menu Configurações na tela de um funil). {% endhint %} 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: ```json { "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 {% hint style="info" %} Pré-requisito: seu funil precisa ter um status de \*\*\*perdido\*\*\* configurado (no menu Configurações na tela de um funil). {% endhint %} 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: ```json { "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: ```json { "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: ```json { "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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://bolten.gitbook.io/bolten-docs/configuracoes-avancadas/webhooks.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.