Creating a webhook
Learn how to create a webhook.
You create a webhook to receive notifications using the following steps:
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.
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.
The following table describes the required and optional parameters that can be sent in a create webhook request:
Parameter | Required/Optional | Description |
|---|---|---|
types | Required | |
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. |
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 were 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"
}
Note: An event triggers a webhook to send a notification to you. The Create webhook page lists and describes the available 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.
%20(1).png?alt=media&token=4b017784-a660-46a9-a3cd-52f84f37946e)
- 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.
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.
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.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.Last modified 21d ago