# Creating a webhook
You create a webhook to receive notifications using the following steps:
1. [Open your firewall to trusted Digital River IP addresses](#step-1-open-your-firewall-to-trusted-digital-river-ip-addresses).
2. [Create a webhook endpoint](#step-2-create-a-webhook-endpoint).
3. [Create webhooks](#step-3-create-webhooks).
4. [Respond to webhook events](#step-4-respond-to-webhook-events).
5. [Check signatures](#step-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](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/webhooks/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](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/events) object.
## Step 3. Create webhooks
You can either create a webhook [programmatically](#create-a-webhook-programmatically) or from the [Digital River Dashboard](#create-a-webhook-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](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1/event-types). |
| `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](https://www.digitalriver.com/docs/digital-river-api-reference/#tag/Events) 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:
{% tabs %}
{% tab title="POST/webhooks" %}
```javascript
curl --location --request POST 'https://api.digitalriver.com/webhooks' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ' \
--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"
}'
```
{% endtab %}
{% endtabs %}
A Webhook with a unique identifier and the default `transportType` of `HTTP` is returned in the response.
{% hint style="warning" %}
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.
{% endhint %}
{% tabs %}
{% tab title="201 Created response" %}
```java
{
"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"
}
```
{% endtab %}
{% endtabs %}
### Create a webhook from the Digital River Dashboard
Instructions for creating a webhook from the Dashboard are [here](https://docs.digitalriver.com/digital-river-api/administration/dashboard/developers/webhooks/creating-a-webhook#step-3-create-webhooks).
{% hint style="info" %}
**Note:** An event triggers a webhook to notify you. The [Create webhook page](https://docs.digitalriver.com/digital-river-api/administration/dashboard/developers/webhooks/creating-a-webhook) lists and describes the available events.
{% endhint %}
## 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](https://app.gitbook.com/s/ZrhMyLX5esFYS64lNWVW/#response-status-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.\
%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 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](https://dashboard.digitalriver.com)'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](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/webhooks/digital-river-signature) for more information.
## Transport type and attributes
The Webhooks API supports [HTTP](#http-transport-type) and [OAUTH](#oauth-transport-type) transport types. The `transportType` you specify in a [create ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/webhooks#webhooks-1)or [update ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/webhooks#webhooks-id-1)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.
{% hint style="warning" %}
The `authentication` hash table is only accepted in the request and displayed in the response when `transportType` is `HTTP`.
{% endhint %}
### 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.
{% hint style="warning" %}
The `oauth` hash table is only accepted in the request and displayed in the response when `transportType` is `OAUTH`.
{% endhint %}
The `tokenEndPoint` is used to exchange an authorization grant for an access token. The `clientID` is issued to you during the [registration process](https://tools.ietf.org/html/rfc6749#section-2.3.1). The `clientSecret`is 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`.