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:

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.