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¶

Each HTTP request is signed with an X-DIDWW-Signature HTTP header.

DIDWW uses the parameters sent in the webhook and the exact URL your application supplied to DIDWW to create this signature.

The signature uses the HMAC-SHA1 hashing algorithm with your DIDWW account’s API Key as the secret key.

Your application can verify that this signature is correct using the server side DIDWW SDKs:

didww-v3 Ruby gem

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

You will need your account’s API Key, the value of the X-DIDWW-Signature HTTP header that DIDWW passed to you, the URL that DIDWW sent the webhook to, and all of the parameters sent by DIDWW.

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.