Creating a webhook

Learn how to create 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 must 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 body contains the complete event details, which you can use after parsing the JSON into an Event object.

Step 3. Create webhooks

You can either create a webhook programmatically or from the Digital River 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

curl --location --request POST 'https://api.digitalriver.com/webhooks' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_key>' \
--data-raw '{
  "types": ["order.accepted", "order.charge.pending", "order.charge.cancel.failed"],
  "apiVersion": "default",
  "enabled": true,
  "authentication":{
      "userName": "some username",
      "password": "some password"
  },
  "address": "https://company.com"
}'

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 was still accepted and returned in the response. This is because HTTP is the default setting.

201 Created response

{
    "id": "177ef997-db7f-42f5-a28d-b0a1ee1267e9",
    "types": [
        "order.charge.cancel.failed",
        "order.charge.pending",
        "order.accepted"
    ],
    "address": "https://company.com",
    "apiVersion": "default",
    "enabled": true,
    "liveMode": false,
    "transportType": "HTTP",
    "authentication": {
        "userName": "some username",
        "password": "some password"
    },
    "createdTime": "2020-11-19T15:44:34.622Z",
    "updatedTime": "2020-11-19T15:44:34.622Z"
}

Create a webhook from the Digital River Dashboard

Instructions for creating a webhook from the Dashboard are here.

Note: An event triggers a webhook to notify you. The Create webhook page lists and describes the available events.

Step 4. Respond to webhook events

Your endpoint must return a 2xx HTTP status code to acknowledge the receipt of an event. If it fails to acknowledge events for several days, it will be disabled.

You did not receive the event if Digital River receives any response codes outside this range. 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 drop-down list in the Dashboard.
2. Go through the same configuration steps again to configure an endpoint for your live integration.

If you use 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 must retrieve your endpoint's token from the Digital River 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 Webhooks 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 specifying this parameter in the request is not required. 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 an encrypted format, but it is decrypted when exposed through the API. This is also true for the optional password parameter within oauth.