Creating a webhook

You create a webhook to receive notifications using the following steps:
1.​Open your firewall to trusted Digital River IP addresses.
2.​Create a webhook endpoint.
3.​Create webhooks.
4.​Respond to webhook events.
5.​Check signatures.
Step 1. Open your firewall to trusted Digital River IP addresses
To receive webhook notifications from Digital River, you'll need to open your firewall to all the IP addresses listed in the Digital River safelist.
Step 2. Create a webhook endpoint
You can send webhook data as JSON in the POST request body. The POST request body contains the complete event details, and you can use it after parsing the JSON into an Event object.
Step 3. Create webhooks
You can either create a webhook programmatically or from the Dashboard.
Create a webhook programmatically
The following table describes the required and optional parameters that can be sent in a create webhook request:
Parameter
Required/Optional
Description
types
Required
Each element of the array represents a type of event.
apiVersion
Optional
Indicates whether to use the current default version of the API or the latest version of the API. The enumerators are latest and default.

The default setting is default.
enabled
Optional
Indicates whether the webhook is enabled and receives notifications.
The default is true.
address
Required
URL of the webhook endpoint on your server that you set up to receive webhook notifications. We send webhook data as JSON in a POST request body. The full event details are included and can be used directly after parsing the JSON into an Event object.
transportType
Optional
Indicates whether the transport type is HTTP or OAUTH.

The default is HTTP.

Refer to transport type and attributes for more information.
Example create request and response
The following POST/webhooks request creates a Webhook for three different event types:
POST/webhooks
1
curl --location --request POST 'https://api.digitalriver.com/webhooks' \
2
--header 'Content-Type: application/json' \
3
--header 'Authorization: Bearer <API_key>' \
4
--data-raw '{
5
  "types": ["order.accepted", "order.charge.pending", "order.charge.cancel.failed"],
6
  "apiVersion": "default",
7
  "enabled": true,
8
  "authentication":{
9
      "userName": "some username",
10
      "password": "some password"
11
  },
12
  "address": "https://company.com"
13
}'
Copied!
A Webhook with a unique identifier and the default transportType of HTTP is returned in the response.
Even though HTTP was not explicitly passed as the transportType in the above request, the userName and password parameters within the authentication hash table were still accepted and returned in the response. This is because HTTP is the default setting.
201 Created response
1
{
2
    "id": "177ef997-db7f-42f5-a28d-b0a1ee1267e9",
3
    "types": [
4
        "order.charge.cancel.failed",
5
        "order.charge.pending",
6
        "order.accepted"
7
    ],
8
    "address": "https://company.com",
9
    "apiVersion": "default",
10
    "enabled": true,
11
    "liveMode": false,
12
    "transportType": "HTTP",
13
    "authentication": {
14
        "userName": "some username",
15
        "password": "some password"
16
    },
17
    "createdTime": "2020-11-19T15:44:34.622Z",
18
    "updatedTime": "2020-11-19T15:44:34.622Z"
19
}
Copied!
Create a webhook from the Dashboard
Instructions for creating a webhook from the Dashboard are here.
Step 4. Respond to webhook events
Your endpoint must return a 2xx HTTP status code to acknowledge the receipt of an event. If the endpoint fails to acknowledge events over several days, your endpoint will be disabled.
If Digital River receives any response codes outside this range, it indicates that you did not receive the event. For example, Digital River treats a URL redirection as a failure.
Once you have verified your endpoint can receive, acknowledge, and handle events correctly:
1.Click Test and select Production from the dropdown list in the Dashboard.
​
2.Go through the same configuration steps again to configure an endpoint for your live integration.
If you're using the same endpoint for both test and production environments, the signing token is unique to each data mode.
Step 5. Check signatures
To verify signatures, you need to retrieve your endpoint's token from the Dashboard's Webhooks settings. To see an endpoint's token:
1.From the Webhooks page on the Dashboard, click the Reveal token or Reveal test token associated with the endpoint you want to verify.
2.Provide your credentials and click Authenticate. The Token field under Signing secret will display the token.
See Digital River signature for more information.
Transport type and attributes
The Webhoooks API supports HTTP and OAUTH transport types. The transportType you specify in a create or update Webhook request determines what additional transport attributes you may need to provide.
HTTP transport type
In a Webhook, the transportType is HTTP by default, so it's not required to specify this parameter in the request. Whether you explicitly set the parameter to HTTP or whether you don't provide a value at all, you can still use the authentication hash table to provide a username and password. These values configure basic authentication for webhook callback endpoints.
The authentication hash table is only accepted in the request and displayed in the response when transportType is HTTP.
OAUTH transport type
You can create OAuth2 configured webhooks by setting the transportType parameter to OAUTH. Doing so means the callback is always accompanied by a valid bearer token.
If you set this parameter to OAUTH, then you must provide the tokenEndPoint , clientID, and clientSecret within the oauth hash table.
The oauth hash table is only accepted in the request and displayed in the response when transportType is OAUTH.
The tokenEndPoint is used to exchange an authorization grant for an access token. The clientID is issued to you during the registration process. The clientSecretis stored in encrypted format, but it is decrypted when exposed through the API. This is also true for the optional password parameter within oauth.

Webhooks

Digital River API safelist

Last modified 1mo ago

Export as PDF

Copy link

Contents

Step 1. Open your firewall to trusted Digital River IP addresses

Step 2. Create a webhook endpoint

Step 3. Create webhooks

Create a webhook programmatically

Create a webhook from the Dashboard

Step 4. Respond to webhook events

Step 5. Check signatures

Transport type and attributes

HTTP transport type

OAUTH transport type