Callbacks Details

Callbacks allow you to receive events related to your Orders, Exports, Address Verifications, and Voice Out Trunks via HTTP request.

Order Callback Request Parameters

Configure a callback_url and callback_method attributes for single resource via the REST API, and DIDWW will make an HTTP request (webhook) to that URL whenever an event takes place for it. callback_url can be set to any valid URL. callback_method can be either GET or POST.

With GET request you will receive payload as query parameters. POST request will set the “Content-Type” header to “application/x-www-form-urlencoded” with body formatted according to content type.

In case of order status change DIDWW makes an HTTP request to the callback_url you’ve set with following parameters:

Parameter	Description
id	ID of an order
type	‘orders’
status	‘completed’ or ‘canceled’

Export Callback Request Parameters

Configure a callback_url and callback_method attributes for single resource via the REST API, and DIDWW will make an HTTP request (webhook) to that URL whenever an event takes place for it. callback_url can be set to any valid URL. callback_method can be either GET or POST.

With GET request you will receive payload as query parameters. POST request will set the “Content-Type” header to “application/x-www-form-urlencoded” with body formatted according to content type.

In case of export complete DIDWW makes an HTTP request to the callback_url you’ve set with following parameters:

Parameter	Description
id	ID of an export
type	‘exports’
status	‘completed’

Address Verification Callback Request Parameters

Configure a callback_url and callback_method attributes for single resource via the REST API, and DIDWW will make an HTTP request (webhook) to that URL whenever an event takes place for it. callback_url can be set to any valid URL. callback_method can be either GET or POST.

With GET request you will receive payload as query parameters. POST request will set the “Content-Type” header to “application/x-www-form-urlencoded” with body formatted according to content type.

In case of address verification status change DIDWW makes an HTTP request to the callback_url you’ve set with following parameters:

Parameter	Description
id	ID of an address verification
type	‘address_verifications’
status	‘approved’ or ‘rejected’
reject_reason	only for rejected status

Voice OUT Trunk Callback Request Parameters

Configure a callback_url attribute for single resource via the REST API, and DIDWW will make an HTTP POST request (webhook) to that URL whenever an event takes place for it. callback_url can be set to any valid URL.

In case of Voice OUT Trunk being blocked due to set 24 hour limit value being reached or trunk being unblocked DIDWW makes an HTTP POST request to the callback_url with “Content-Type” header set to “application/json” and body as JSON array with one or more JSON objects.

Each JSON object will have following parameters:

Parameter	Type	Description
id	string	ID of a Voice OUT Trunk
type	string	‘voice_out_trunks’
status	string	‘active’ or ‘blocked’
threshold_reached	boolean	false or true
created_at	string	Date and Time of event creation

Example

[
    {
        "id": "f36d1d17-bd16-42b9-af42-0cfe166bf3ec",
        "type": "voice_out_trunks",
        "status": "blocked",
        "threshold_reached": true,
        "created_at": "2017-06-25T08:21:41.795Z"
    }
]

HTTP Request Validation

If your application exposes sensitive data or is possibly mutative to your data, then you may want to be sure that the HTTP requests to your web application are indeed coming from DIDWW, and not a malicious third party. To allow you this level of security, DIDWW cryptographically signs its requests. Here’s how it works:

Turn on TLS on your server and configure your DIDWW account to use HTTPS URLs in callback_url.
DIDWW assembles and normalizes the payload.
- If your request is a POST, DIDWW takes all the POST fields, sorts them alphabetically by their name, and concatenates the parameters name and value (with no delimiters).
- If your request is a GET, DIDWW takes all the GET query fields (except the query added to the URL itself), sorts them alphabetically by their name, and concatenates the parameters name and value (with no delimiters).
DIDWW normalizes the URL (the full URL with a scheme, port, query string, and fragments), concatenates with normalized payload and sign it using HMAC-SHA1 and your API key as the key.
DIDWW sends this signature in an HTTP header called X-DIDWW-Signature.

Note

Only an API key with the enable_callbacks option enabled will be used. If there is no API key with this option enabled, then no callback will be performed. Therefore, it’s crucial to make sure that the correct API key is being used to generate the X-DIDWW-Signature for the validation process to function properly. Callbacks can be enabled only for a single API key.

Then, on your end, if you want to verify the authenticity of the request, you can leverage the built-in request validation method provided by all of our helper libraries:

didww-v3 Ruby gem

didww/didww-api-3-php-sdk PHP library

Note

We highly recommend you use the helper libraries to do signature validation.

Algorithm implementation details

Steps to perform validation manually:

Take the full URL of the request URL you specify in the callback_url attribute, from the protocol (https…) through the end of the query string (everything after the ?).
If the request is a POST, sort all of the POST parameters alphabetically (using Unix-style case-sensitive sorting order).
If the request is a GET, sort all of the query parameters alphabetically (except that are specifically set in callback_url, using Unix-style case-sensitive sorting order).
For POST requests iterate through the sorted list of POST parameters, and append the variable name and value (with no delimiters) to the end of the URL string.
For GET requests iterate through the sorted list of GET parameters (except that are specifically set in callback_url) and append the variable name and value (with no delimiters) to the end of the URL string.
Sign the resulting string with HMAC-SHA1 using your API key as the key (remember, your API key’s case matters!).
Encode the resulting hash as a hex-encoded string (each byte of result data transformed into hex from 00 to ff, most encryption libraries have a function that returns hex digest on the previous step).
Compare your hash to ours, submitted in the X-DIDWW-Signature header. If they match, then you’re good to go.

Here’s an example. DIDWW made a POST to your application as part of an order callback: .. code-block:

https://mycompany.com/didww_callbacks?opaque=123

And DIDWW posted the following POST fields:

type: orders

status: completed

id: bf2cee72-6caa-4ae2-917e-bea01945691e

Create a string that is your URL with the full query string and explicitly set the port: .. code-block:

https://mycompany.com:443/didww_callbacks?opaque=123

Then, sort the list of POST variables by the parameter name (using Unix-style case-sensitive sorting order):

id: bf2cee72-6caa-4ae2-917e-bea01945691e

status: completed

type: orders

Next, append each POST variable, name and value, to the string with no delimiters: .. code-block:

https://mycompany.com:443/didww_callbacks?opaque=123idbf2cee72-6caa-4ae2-917e-bea01945691estatuscompletedtypeorders

Hash the resulting string using HMAC-SHA1, using following test API key szrdgh6547umt7tht7xbqhj6g9gdbyp7 and encode as a hex-encoded string

The resulting signature should be 30f66e9d72eb5e193051fd02952f70d8e934b4ff

Note

Concerned about SHA1 security issues? DIDWW does not use SHA-1 alone. In short, the critical component of HMAC-SHA1 that distinguishes it from SHA-1 alone is the use of your DIDWW API key as a complex secret key. While there are possible collision-based attacks on SHA-1, HMACs are not affected by those same attacks - it’s the combination of the underlying hashing algorithm (SHA-1) and the strength of the secret key (API key) that protects you in this case.

IP addresses

Requests are being sent from IPv4 network 46.19.208.0/21 and IPv6 network 2a01:ad00::/32

HTTP Response Error Handling

When DIDWW receives non 2XX response status code from an HTTP request to the callback_url it will re-attempt to send it again up to 9 times.

After 10 attempt DIDWW will stop sending callback event.

HTTP request timeout more than 60 seconds will consider as failed response.

Callback attempt	Wait interval
2	1 minute
3	10 minutes
4	30 minutes
5	1 hour
6	3 hours
7	6 hours
8	12 hours
9	1 day
10	2 days

Testing Callbacks on local machine behind NAT

In order to test Callbacks feature on local servers behind NAT, tools such as ngrok or localtunnel could be used. These tools allows you to expose a web server running on your local machine to the internet.