Callbacks Details

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

Configure a callback_url and callback_method attributes when these objects using the REST API, and DIDWW will make an HTTP request (webhook) to that URL whenever an event takes place for them. 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.

Order Callback Request Parameters

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

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

‘cdr_exports’

status

‘completed’

Address Verification Callback Request Parameters

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

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 ngrock or localtunnel could be used. These tools allows you to expose a web server running on your local machine to the internet.