Webhooks

✨ Welcome to our Webhooks Beta!

This feature is currently in Beta, which means we are still actively developing it. We will add more event types and features based on your feedback. If there is a specific event you need, please do not hesitate to contact our support team.

What are Webhooks?

Webhooks are how Bolten sends real-time data to your other applications whenever a specific event happens in your project. We will proactively send a notification (a request POST), along with details and information, to a URL you provide.

This is great for cases like:

• Automating communications across multiple channels when a lead changes stage.

• Scheduling actions in other platforms at certain stages of a lead.

When to use Webhooks vs. our API

• Use Webhooks when you want to be notified immediately about an event that occurred in Bolten and/or have a flow to be triggered from something happening in your project.

• (Coming soon) Use our API when you want to proactively fetch data from Bolten or update information in Bolten from another system.

---

How to set up

See how you can set up your first webhook in just a few steps.

1. Accessing Webhooks

You can find the Webhooks settings within a project in Bolten under Settings > Integrations > Webhooks.

2. Creating a New Webhook

1. On the Webhooks page, click the "+ Webhook". 2. You will see a configuration screen where you will need to fill in some details:

• Endpoint URL: This is the URL of your application where you want to receive the webhook data.

• Name: A friendly name to help you remember what this webhook is for (e.g., "Slack Notifications for Won Deals").

• Events: Check the boxes for the events you want to be notified about.

---

Authentication

To ensure your data is sent securely, we offer some ways to authenticate your webhooks.

Unauthenticated (no authentication)

This option does not add any security to your webhook requests. It is useful for testing or for sending data to internal, non-critical services.

Basic Auth

If your endpoint is protected with HTTP Basic Authentication, we will send the following in the request headers:

Authorization: Basic <base64(user:password)>

API Key

We can include a secret API Key in the headers of each request we send. This is a secure and recommended method. We will add the following header to each request:

X-API-KEY: YOUR_SECRET_KEY

You can then verify this key on your server to ensure the request is coming from Bolten.

Bearer Token

You can also configure authentication via a Bearer header:

Authorization: Bearer <token>

---

Events and Payloads

Important: within the opportunity, all (and only) the fields configured in your project's opportunity will be sent. The same applies to the contact linked to the opportunity.

Funnel

OpportunityWon

Prerequisite: your funnel needs to have a ***won*** status configured (in the Settings menu on the funnel screen).

Triggered when an opportunity is moved to the stage configured as "won".

Note: in addition to this event, an opportunity.transitioned.

Request body example:

{
  "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": "Lead Name",
      "E-mail": "[e-mail]",
      "Status": "Done",
      "Contact": {
        "Name": "Lead Name",
        "E-mail": "[e-mail]",
        "Phone": "5511999999999"
      },
      "Tasks": [
        {
          "id": "f6f8fede-5814-49f0-8dc3-810daea7747b",
          "state": "to_do",
          "title": "Example task",
          "created_at": "2025-07-24T11:30:00.541-03:00",
          "updated_at": "2025-07-24T11:30:00.541-03:00",
          "description": "Example task",
          "scheduled_to": "2023-12-28T00:00:00.000-03:00"
        }
      ],
      "Products": [
        {
          "id": "9f435f4a-9f52-420e-a2bf-f7a99a90af77",
          "quantity": 2,
          "product_name": "Product A",
          "final_price_cents": 24600,
          "product_price_cents": 12300,
          "final_price_currency": "BRL",
          "product_price_currency": "BRL"
        }
      ]
    }
  }
}

OpportunityLost

Prerequisite: your funnel needs to have a ***lost*** status configured (in the Settings menu on the funnel screen).

Triggered when an opportunity is moved to the stage configured as "lost".

Note: in addition to this event, an opportunity.transitioned.

Request body example:

{
  "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": "Lead Name",
      "E-mail": "[e-mail]",
      "Status": "Done",
      "Contact": {
        "Name": "Lead Name",
        "E-mail": "[e-mail]",
        "Phone": "5511999999999"
      },
      "Tasks": [
        {
          "id": "f6f8fede-5814-49f0-8dc3-810daea7747b",
          "state": "to_do",
          "title": "Example task",
          "created_at": "2025-07-24T11:30:00.541-03:00",
          "updated_at": "2025-07-24T11:30:00.541-03:00",
          "description": "Example task",
          "scheduled_to": "2023-12-28T00:00:00.000-03:00"
        }
      ],
      "Products": [
        {
          "id": "9f435f4a-9f52-420e-a2bf-f7a99a90af77",
          "quantity": 2,
          "product_name": "Product A",
          "final_price_cents": 24600,
          "product_price_cents": 12300,
          "final_price_currency": "BRL",
          "product_price_currency": "BRL"
        }
      ]
    }
  }
}

OpportunityTransitioned

Triggered when an opportunity is moved from one stage to another.

Note: this event is also emitted when an opportunity.won or opportunity.lost. Additionally, if the transition is to a status configured as won or lost, the corresponding events will also be triggered.

Request body example:

{
  "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": "Lead Name",
      "E-mail": "[e-mail]",
      "Status": "Done",
      "Contact": {
        "Name": "Lead Name",
        "E-mail": "[e-mail]",
        "Phone": "5511999999999"
      },
      "Tasks": [
        {
          "id": "f6f8fede-5814-49f0-8dc3-810daea7747b",
          "state": "to_do",
          "title": "Example task",
          "created_at": "2025-07-24T11:30:00.541-03:00",
          "updated_at": "2025-07-24T11:30:00.541-03:00",
          "description": "Example task",
          "scheduled_to": "2023-12-28T00:00:00.000-03:00"
        }
      ],
      "Products": [
        {
          "id": "9f435f4a-9f52-420e-a2bf-f7a99a90af77",
          "quantity": 2,
          "product_name": "Product A",
          "final_price_cents": 24600,
          "product_price_cents": 12300,
          "final_price_currency": "BRL",
          "product_price_currency": "BRL"
        }
      ]
    }
  }
}

OpportunityCreated

Triggered when an opportunity is created.

Request body example:

{
  "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": "Lead Name",
      "E-mail": "[e-mail]",
      "Status": "Done",
      "Contact": {
        "Name": "Lead Name",
        "E-mail": "[e-mail]",
        "Phone": "5511999999999"
      },
      "Products": [
        {
          "id": "9f435f4a-9f52-420e-a2bf-f7a99a90af77",
          "quantity": 2,
          "product_name": "Product A",
          "final_price_cents": 24600,
          "product_price_cents": 12300,
          "final_price_currency": "BRL",
          "product_price_currency": "BRL"
        }
      ]
    }
  }
}

---

Error Handling and Retries

How Bolten Handles Failures

If your endpoint does not respond with a 2xx status code (e.g., 200 OK), we will consider the delivery a failure. We will then attempt to resend the webhook 5 more times, with exponential backoff intervals between each attempt. If all retries fail, we will stop sending that specific event.

Viewing Deliveries

On the webhook details page, you can see a log of recent deliveries. For troubleshooting purposes, we display only the most recent request and response for each webhook invocation.

---

Best Practices

Here are some tips to make your webhook integration as reliable as possible:

• Respond Quickly: Receive webhooks by returning a 200 OK status as quickly as possible. Avoid performing complex logic before sending the response. It's better to receive the data, respond, and then process it asynchronously.

• Handle Duplicates: In rare cases, your endpoint may receive the same webhook more than once. Design your system to be idempotent (i.e., able to handle duplicate events without causing issues).

• Keep Your Keys Secure: Treat your API Key as a password. Do not expose it in client-side code or public repositories.