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 Management API, it’s more practical to rely on the already existing automation feature, such as callbacks.
Voximplant offers you a variety of callbacks and, in this article, we’ll explore how MinBalanceCallback is used. With callbacks, the Voximplant HTTP Management API becomes even more useful in terms of better integration and monitoring.
WHAT YOU NEED
Go to the Webhooks section of the Voximplant control panel and click Add in the middle of the screen. The two boxes will appear: 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.
CALLBACKS IN ACTION
The Voximplant cloud sends the HTTP POST requests with one or several callbacks to your backend server.
- type – the callback type that determines which properties contain data. The min_balance type means MinBalanceCallback
- hash – the hash calculated by the Voximplant cloud
- сallbackId – a unique number of the callback, which is used to calculate the hash
For more information, see the Management 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 Management 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:
Make your server communicate with the Voximplant HTTP Management 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.