HTTP API callbacks


HTTP Callbacks allow getting important notifications without frequently sending HTTP requests from your backend to the Voximplant cloud. Instead of creating additional scripts that send requests to our HTTP API, it’s more practical to rely on the already existing automation feature, such as allbacks. Voximplant offers you a variety of callbacks and, in this article, we’ll explore how MinBalanceCallback is used. With callbacks, the Voximplant HTTP API becomes even more useful in terms of better integration and monitoring.


  • Voximplant developer account. If you don’t have one, sign up here.
  • Basic knowledge of the Voximplant HTTP API.
  • A simple backend. We will use the node.js server as an example.


Go to the API Access section of the Voximplant control panel. This section contains two boxes: Callback URL and Security salt. Technically, only the Сallback URL box is required to enable callbacks while the Security salt box is optional. However, in this article, we will check the hash, that’s why both boxes must be filled in.

In the Callback URL box, specify the URL of your backend server. The Security salt box can contain cryptographic salt, which is an arbitrary text string up to 40 characters.

A callback will use the Security salt value to calculate the MD5 hash, which is retrieved by your backend server as part of an AccountCallback JSON object.

When you fill in both boxes, click Save. Now you can use the Voximplant callbacks and check the hash.


The Voximplant cloud sends the HTTP POST requests with one or several callbacks to your backend server.

The request body will contain an object with the account callback array. The array contains the AccountCallback JSON object with the following fields:

  • type – the callback type that determines which properties contain data. The min_balance type means MinBalanceCallback.
  • hash – the hash calculated by the Voximplant cloud.
  • сallback_id – a unique number of the callback, which is used to calculate the hash.
  • For more information, see the HTTP API documentation.

For example, if the balance reaches the specified threshold, the callback list will contain a MinBalanceCallback callback. The backend server can do anything with that information: send a letter to your support team, store the alert timestamp, etc. The handlers are up to you — set up any handling rules you want. For illustrative purposes, we will write a debug message to the server console.


The Voximplant HTTP API can communicate with the PHP/Node.js/nginx and other backend solutions. To get things done quickly, we will use the Express framework for node.js.

Install node.js and express.js on any server platform (AWS, Azure or any VDS, etc.). You can also test the solution locally using ngrok, which allows testing demo applications from your local computer without deploying them with a public IP address.

Since the Security salt value was set, it’s possible to save it to the backend server to check the hash later. As you can see on the figure in the first paragraph, the MD5 algorithm is used to calculate the hash:

md5(Security salt + account_id + api_key + callback_id)

The backend server stores the Security salt, account_id, and api_key values. When the callback is triggered, the server receives hash and callback_id. Then the server calculates the hash and compares the calculated value with the received one. If the values match, everything is OK; otherwise, the callback is corrupted or triggered not from the Voximplant cloud.

Let’s create the index.js file with the following code:

const express = require('express');
const crypto = require('crypto');

const app = express();
const salt = "<salt string>";
const accountId = "<account id string>";
const apiKey = "<api key string>";

app.use(express.json());'/', (req, res) => {
  for (callback of req.body.callbacks) {
    const data = salt + accountId + apiKey + callback.callback_id;
    hash = crypto.createHash('md5').update(data).digest('hex');
    if (hash === callback.hash) {
      if (callback.type === 'min_balance') {
        console.log("WARNING! The balance is under the threshold!");

app.get('/', (req, res) => {



Make your server communicate with the Voximplant HTTP API to get even more control of your account. Receive the alerts on time or check the information manually – the callbacks obviously aid you in keeping the account data close at hand. Enjoy the functionality and stay tuned!

Add your comment

Please, enter valid email

Get your free developer account or talk with our sales team to learn more about Voximplant solutions
Contact sales

Please complete this field.

Please complete this field.

Please complete this field.

Choose the solution

Please complete this field.

Please complete this field.