Secure API communications
To secure your API communications, follow the steps for both directions: from Infobip to your application, and from your application to Infobip.
From Infobip to your application
By default, Infobip will post data to your application's CallbackURL and StatusURL without any specific security scheme other than using HTTPS communications, provided your exposed URLs support HTTPS. If you wish to enhance the security of these communications, you can request Infobip to include an Authorization header to every post made toward your CallbackURL and StatusURL.
Here are the steps you need to do to be able to use an Authorization header.
Step 1 Use method to create a new number masking credential
Use the POST/voice/masking/2/credentials method to create a new number masking credential
The method will reply with a 200 OK to confirm both apiID and key values in the response's payload.
A credential composes of two key parts the user generates (apiID and key), both being alphanumerical strings (80 characters max).
Once your credentials are confirmed, any data posted to your application's CallbackURL and StatusURL will have an Authorization header whose value is computed based on your keys.
Note that number masking credentials are not application-specific. If you have multiple number masking configurations, the same apiID and key are used to build the Authorization header's content.
Step 2 Understand the Authorization header's content
Authorization headers generated by Infobip and added to POST requests to your application's CallbackURL and StatusURL are built on the following logic:
Where:
webhookURLis the URL of your Callback or Status webhookrequestBodyis the body of the message posted to your Callback or Status webhookapiKeyis the first part of your number masking credentialskeyis the second part of your number masking credentials The hashing algorithm is SHA256.
This example uses the CallbackURL https://my.company.server/nmcallback and Infobip sends the following message towards that URL:
This example uses the following number masking credentials:
Infobip then adds the Authorization header that is shown as:
The value of the header is:
Step 3 Status callback particularities
When computing the Authorization header for messages sent to your Status URL, Infobip will purposely omit 3 key value pairs from the message body. The affected keys are:
- calculatedDuration
- currency
- pricePerSecond
If the body of the message received from the statusURL is:
What this means is that the Authorization header takes only the following elements into account:
Step 4 Validating incoming messages to your application's Callback and Status URLs
When you receive a message from Infobip to your Callback or StatusURLs, you need to apply the same logic as explained from Steps 2 and 3 to compute what should be the expected Authorization value and compare it to the one you will receive in the message. If the values match, you can be sure that this message was sent by Infobip and is safe.
When concatenating your webhookURL, body and key and before hashing that concatenated string, make sure to strip off any potential new line characters from the body. New lines would not appear when string concatenation and hashing is performed by your application code, but can happen in debugging phase if you copy/paste the body content manually in text editors.
From your application to Infobip
Although not a specific feature in number masking, if you wish to add an extra layer of security to HTTP requests your application sends to Infobip, you can generate a specific API Key that will be limited to predefined IP addresses. The IP address(es) are the fixed address(es) behind your application. On the API Key Management page of the Infobip web interface, you can easily create an API key and assign your IPs: