What are webhooks?

Sending JSON webhooks is an efficient way to transfer data from one application to another in real-time. This process involves the use of a webhook URL, which is provided by the receiving application (Brightcall in this case), and acts as a phone number that the other application can call when an event occurs. The data is then sent over the web from the application where the event originally occurred, to the receiving application that handles the data. This data is known as the “payload” and is usually sent in either JSON or XML format.

How to send data with webhooks to trigger a Speed To Lead™ call ?

Our webhook expands on ways you can connect with your leads by turning webforms, shopping carts, or anything you want into an opportunity to be the first to lead.

Now let’s look at some code examples of sending a JSON webhook to Brightcall:

1. Save Brightcall's request URL and choose if you prefer to submit a GET or POST request.

https://app.brightcall.ai/rest/v1/ext/add_call_api/

2. Add keys and values according to the examples below. More info on how to find your personal widget key and API key can be found here → How to get a Widget Key? and How to get an API Key?

⚠️Note: Please use the widget’s API key — not the account API key.

This is a common mistake and will prevent the webhook from triggering correctly if done wrong.

👇 JSON Header for POST method

Key	Value
Content-Type	application/json

👇 JSON Body for POST method and minimum required fields

Key	Value
widget_key	%WIDGET_KEY%
api_key	%API_KEY%
lc_number	+1234567890

👇 Example: Combined JSON object for POST method and minimum required fields

'headers': { 
      'Content-Type': 'application/json', 
}, 

 'body':  { 
  'widget_key': '%WIDGET_KEY%', // The widget key of the widget you want to trigger
  'api_key': '%WIDGET_API_KEY%', // The API key of this same widget (not account-level)
  'lc_number': '+1234567890' // leads's phone number 
}

👇 Example: GET method and minimum required fields

https://app.brightcall.ai/rest/v1/ext/add_call_api/?widget_key={WIDGET_KEY}&api_key={WIDGET_API_KEY}&lc_number={number}

3. Now, you should have all that it takes to trigger a call to Brightcall. But, you can submit additional data from form fields as needed by including optional custom parameters (you can find out more about custom parameters in our dedicated article here):

 "headers'": {
   "Content-Type": "application/json",
 },

 "body": {
     "widget_key": "%WIDGET_KEY%",
     "api_key": "%WIDGET_API_KEY%", 
     "lc_number": "+1234567890" 
     "lc_param_name": "John Doe", // lead's name
     "lc_param_email": "[email protected]", // lead's email
     "lc_param_message": "Hello, world!", // Message
     "lc_number_2": "+1234567892" // optional lead's second phone number
     "country": "UK" // two letter ISO country code used for local number format conversion, if needed
}

4. If you followed all the steps correctly, you should have a powerful API request ready to impress your leads. Great work! 🎉

Pass agent’s info into the webhook [optional]

Agents can also be defined using our webhook, meaning that you can send calls to a specific agent or even agents who are not defined in the call queue in the Brightcall Dashboard.

In order to trigger a call at agents phone number, you just need to add the custom parameters such as "lc_param_agent01name" and "lc_param_agent01phone". Then just fill the values with the contact information from your agent(s) as shown below.

"lc_param_agent01name": "James Smith", "lc_param_agent01phone":"+1234567890"

lc_param_agent<replace this with your number of choice>name - custom agent name (e.g. lc_param_agent01name)

lc_param_agent<use the same number you set in the above field>phone - custom agent phone (e.g. lc_param_agent01phone). Phone numbers can be with trailing zero or without.

Example

To connect John Doe (a lead) with James, Anna or Ahmad (agents), we need to list information of the lead and the agents in the following format.

 "headers'": {
   "Content-Type": "application/json",
 },

 "body": {
     "widget_key": "%WIDGET_KEY%",
     "api_key": "%WIDGET_API_KEY%", 
     "lc_number": "+1234567890" 
     "lc_param_name": "John Doe", // lead's name
     "lc_param_email": "[email protected]", // lead's email
     "lc_param_message": "Hello, world!", // Message
     "lc_number_2": "+1234567892" // optional lead's second phone number
     "country": "US"
     "lc_param_agent01name": "James Smith",   // Agent 1
     "lc_param_agent01phone":"+1234567890"
     "lc_param_agent02name": "Anna Williams", // Agent 2 
     "lc_param_agent02phone":"+44234567890"
     "lc_param_agent03name": "Ahmad Khaled",  // Agent 3
     "lc_param_agent03phone":"+97123567890"

}

Then we need to define how the calls will be distributed among James, Anna and Ahmad. Call distribution among the agents can be defined inside of the Dashboard under a section called "Call Routing". In the screenshot below you can find all the call distribution types available by the Brightcall system.

🕓 Scheduling Calls at a Specific Time (Optional)

You can schedule a call to occur at a specific date and time using the optional future_unixstamp parameter.

This is useful if your lead selects a preferred time for the call in a form or webapp.

Key points:

future_unixstamp is a Unix timestamp in seconds (UTC).
It is added directly to the API request JSON body — no custom field creation is needed.
If omitted, Brightcall behaves as usual: triggers the call immediately if within working hours, or schedules it for the earliest available slot based on your widget schedule.

Example: Regular Call Trigger + Future Timestamp

{   
  "headers": {
     "Content-Type": "application/json"
 },
 "body": {
   "widget_key": "%WIDGET_KEY%",
   "api_key": "%WIDGET_API_KEY%",
   "lc_number": "+1234567890",
   "lc_param_name": "John Doe",  // lead's name
   "lc_param_email": "[email protected]",  // lead's name
   "lc_param_message": "Hello, world!",  // Message
   "lc_number_2": "+1234567892",  // optional lead's second phone number
   "country": "US",
   "lc_param_agent01name": "James Smith",     // Agent 1
   "lc_param_agent01phone": "+1234567890",
   "lc_param_agent02name": "Anna Williams",   // Agent 2
   "lc_param_agent02phone": "+44234567890",
   "lc_param_agent03name": "Ahmad Khaled",   // Agent 3
   "lc_param_agent03phone": "+97123567890",
   "future_unixstamp": 1739017200
 }
}

Explanation:

future_unixstamp: 1739017200 → corresponds to Feb 11, 2025, 15:00 UTC (16:00 Stockholm time).
All other fields remain the same as a normal call trigger request.
You can still include optional fields such as multiple agent info, lead messages, or additional phone numbers.

This allows you to send scheduled calls programmatically, giving your leads the flexibility to pick a convenient time while keeping the standard Speed To Lead™ API workflow intact.

If you have any questions, please email us at [email protected]

Making a call through an API request