Webhooks

✨ ¡Bienvenido(a) a nuestra versión Beta de Webhooks!

Esta funcionalidad está actualmente en Beta, lo que significa que todavía la estamos desarrollando activamente. Añadiremos más tipos de eventos y funcionalidades basadas en sus comentarios. Si hay un evento específico que necesita, por favor, no dude en contactar a nuestro equipo de soporte.

¿Qué son los Webhooks?

Los Webhooks son la forma que Bolten utiliza para enviar datos en tiempo real a sus otras aplicaciones siempre que ocurra un evento específico en su proyecto. Enviaremos proactivamente una notificación (una request POST), junto con detalles e información, a una URL que usted proporcione.

Esto es ideal para casos como:

• Automatizar comunicaciones por diversos canales cuando un lead cambia de etapa.

• Realizar agendamientos en otras plataformas en determinadas etapas de un lead.

Cuándo usar Webhooks vs. nuestra API

• Use Webhooks cuando quiera ser notificado inmediatamente sobre un evento que ocurrió en Bolten y/o tenga un flujo que deba ser activado a partir de algún suceso en su proyecto.

• (Próximamente) Use nuestra API cuando quiera obtener datos de Bolten de forma proactiva o actualizar información en Bolten desde otro sistema.

---

Cómo configurar

Vea cómo puede configurar su primer webhook en solo unos pasos.

1. Accediendo a los Webhooks

Puede encontrar la configuración de Webhooks dentro de un proyecto en Bolten en Configuración > Integraciones > Webhooks.

2. Creando un Nuevo Webhook

1. En la página de Webhooks, haga clic en el botón "+ Webhook". 2. Verá una pantalla de configuración donde deberá completar algunos detalles:

• URL del Endpoint: Esta es la URL de su aplicación donde desea recibir los datos del webhook.

• Nombre: Un nombre amigable para ayudarle a recordar para qué sirve este webhook (ej: "Notificaciones en Slack para Negocios Ganados").

• Eventos: Marque las casillas de los eventos sobre los que desea ser notificado.

---

Autenticación

Para garantizar que sus datos se envíen de forma segura, ofrecemos algunas maneras de autenticar sus webhooks.

Unauthenticated (sin autenticación)

Esta opción no añade ninguna seguridad a sus solicitudes de webhook. Es útil para pruebas o para enviar datos a servicios internos y no críticos.

Basic Auth

Si su endpoint está protegido con Autenticación HTTP Básica, enviaremos lo siguiente en los headers de las requests:

Authorization: Basic <base64(user:password)>

API Key

Podemos incluir una Clave de API (API Key) secreta en las cabeceras de cada solicitud que enviemos. Este es un método seguro y recomendado. Añadiremos la siguiente cabecera a cada petición:

X-API-KEY: SU_CLAVE_SECRETA

Usted puede entonces verificar esta clave en su servidor para asegurarse de que la solicitud proviene de Bolten.

Bearer Token

También puede configurar autenticación vía header Bearer:

Authorization: Bearer <token>

---

Eventos y Payloads

Importante: dentro del campo opportunity, se enviarán todos (y solo) los campos configurados en la oportunidad de su proyecto. Lo mismo aplica para el contacto que esté vinculado a la oportunidad.

Embudo

OpportunityWon

Prerequisito: su embudo necesita tener un estado de ***ganado*** configurado (en el menú Configuración en la pantalla de un embudo).

Disparado cuando una oportunidad se mueve a la etapa configurada como "ganado".

Observación: además de este evento, también se disparará un opportunity.transitioned.

Ejemplo del cuerpo de la solicitud:

{
  "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": "Nombre del Lead",
      "E-mail": "[e-mail]",
      "Status": "Done",
      "Contacto": {
        "Nome": "Nombre del Lead",
        "E-mail": "[e-mail]",
        "Telefone": "5511999999999"
      },
      "Tarefas": [
        {
          "id": "f6f8fede-5814-49f0-8dc3-810daea7747b",
          "state": "to_do",
          "title": "Tarea ejemplo",
          "created_at": "2025-07-24T11:30:00.541-03:00",
          "updated_at": "2025-07-24T11:30:00.541-03:00",
          "description": "Tarea de ejemplo",
          "scheduled_to": "2023-12-28T00:00:00.000-03:00"
        }
      ],
      "Productos": [
        {
          "id": "9f435f4a-9f52-420e-a2bf-f7a99a90af77",
          "quantity": 2,
          "product_name": "Producto A",
          "final_price_cents": 24600,
          "product_price_cents": 12300,
          "final_price_currency": "BRL",
          "product_price_currency": "BRL"
        }
      ]
    }
  }
}

OpportunityLost

Prerequisito: su embudo necesita tener un estado de ***perdido*** configurado (en el menú Configuración en la pantalla de un embudo).

Disparado cuando una oportunidad se mueve a la etapa configurada como "perdido".

Observación: además de este evento, también se disparará un opportunity.transitioned.

Ejemplo del cuerpo de la solicitud:

{
  "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": "Nombre del Lead",
      "E-mail": "[e-mail]",
      "Status": "Done",
      "Contacto": {
        "Nome": "Nombre del Lead",
        "E-mail": "[e-mail]",
        "Telefone": "5511999999999"
      },
      "Tarefas": [
        {
          "id": "f6f8fede-5814-49f0-8dc3-810daea7747b",
          "state": "to_do",
          "title": "Tarea ejemplo",
          "created_at": "2025-07-24T11:30:00.541-03:00",
          "updated_at": "2025-07-24T11:30:00.541-03:00",
          "description": "Tarea de ejemplo",
          "scheduled_to": "2023-12-28T00:00:00.000-03:00"
        }
      ],
      "Productos": [
        {
          "id": "9f435f4a-9f52-420e-a2bf-f7a99a90af77",
          "quantity": 2,
          "product_name": "Producto A",
          "final_price_cents": 24600,
          "product_price_cents": 12300,
          "final_price_currency": "BRL",
          "product_price_currency": "BRL"
        }
      ]
    }
  }
}

OpportunityTransitioned

Disparado cuando una oportunidad se mueve de una etapa a otra.

Observación: este evento también se emite cuando ocurre un opportunity.won o opportunity.lost. Además, en caso de que la transición sea a un estado configurado como ganado o perdido, también se dispararán los eventos correspondientes.

Ejemplo del cuerpo de la solicitud:

{
  "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": "Nombre del Lead",
      "E-mail": "[e-mail]",
      "Status": "Done",
      "Contacto": {
        "Nome": "Nombre del Lead",
        "E-mail": "[e-mail]",
        "Telefone": "5511999999999"
      },
      "Tarefas": [
        {
          "id": "f6f8fede-5814-49f0-8dc3-810daea7747b",
          "state": "to_do",
          "title": "Tarea ejemplo",
          "created_at": "2025-07-24T11:30:00.541-03:00",
          "updated_at": "2025-07-24T11:30:00.541-03:00",
          "description": "Tarea de ejemplo",
          "scheduled_to": "2023-12-28T00:00:00.000-03:00"
        }
      ],
      "Productos": [
        {
          "id": "9f435f4a-9f52-420e-a2bf-f7a99a90af77",
          "quantity": 2,
          "product_name": "Producto A",
          "final_price_cents": 24600,
          "product_price_cents": 12300,
          "final_price_currency": "BRL",
          "product_price_currency": "BRL"
        }
      ]
    }
  }
}

OpportunityCreated

Disparado cuando se crea una oportunidad.

Ejemplo del cuerpo de la solicitud:

{
  "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": "Nombre del Lead",
      "E-mail": "[e-mail]",
      "Status": "Done",
      "Contacto": {
        "Nome": "Nombre del Lead",
        "E-mail": "[e-mail]",
        "Telefone": "5511999999999"
      },
      "Productos": [
        {
          "id": "9f435f4a-9f52-420e-a2bf-f7a99a90af77",
          "quantity": 2,
          "product_name": "Producto A",
          "final_price_cents": 24600,
          "product_price_cents": 12300,
          "final_price_currency": "BRL",
          "product_price_currency": "BRL"
        }
      ]
    }
  }
}

---

Manejo de Errores y Reintentos

Cómo Bolten Maneja las Fallas

Si su endpoint no responde con un código de estado 2xx (ej: 200 OK), consideraremos la entrega como una falla. Entonces intentaremos reenviar el webhook 5 veces más, con intervalos exponenciales (exponential backoff) entre cada intento. Si todos los reintentos fallan, dejaremos de enviar ese evento específico.

Visualizando Entregas

En la página de detalles del webhook, puede ver un registro de las entregas más recientes. Para fines de solución de problemas, mostramos solo la solicitud y respuesta más recientes por cada invocación de webhook.

---

Buenas Prácticas

Aquí hay algunos consejos para hacer su integración con webhooks lo más fiable posible:

• Responda Rápido: Reciba los webhooks devolviendo un status 200 OK lo antes posible. Evite ejecutar lógicas complejas antes de enviar la respuesta. Es mejor recibir los datos, responder y luego procesarlos de forma asíncrona.

• Maneje los Duplicados: En casos raros, su endpoint puede recibir el mismo webhook más de una vez. Diseñe su sistema para que sea idempotente (es decir, capaz de manejar eventos duplicados sin causar problemas).

• Mantenga sus Claves Seguras: Trate su API Key como una contraseña. No la exponga en el código del lado del cliente (client-side) ni en repositorios públicos.