> For the complete documentation index, see [llms.txt](https://bolten.gitbook.io/bolten-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bolten.gitbook.io/bolten-docs/configuracoes-avancadas/webhooks.md).
# 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.
