Webhooks

Webhooks allow developers to be notified, in near real-time, when specific events occur.

When you register your webhook URLs with Digital River, Digital River creates an Event object and sends webhook events that notify your application any time an event occurs.

The Event object includes the type of event and the data associated with that event. Digital River sends the Event object to the endpoint URLs you define in the Dashboard's Webhook settings for your account through an HTTP POST request. You can set up multiple webhook endpoints to receive a single event.

You create a webhook to send notifications in four easy steps.

Step 1. 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 2. Configure webhooks

When configuring webhooks, you need to add endpoints from the Dashboard:

  1. From the Webhooks page, click Create Webhook.

  2. Toggle Disabled to Enabled.

  3. Enter the URL for the endpoint in the Endpoint URL field.

  4. Select the check box next to each event you want to associate with the endpoint or select the Events Selected check box to select all events.

  5. Click Save.

Create Webhook

Step 3. 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. Toggle from Test to Live 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 live modes, the signing token is unique to each data mode.

Step 4. Check signatures

You can include the Digital River signature if you want Digital River to sign the webhook events it sends to your endpoints. The signature will appear in each event's DigitalRiver-Signature header. You can use the signature to verify that Digital River sent the events, rather than a third party. You can use our libraries to verify signatures, or you can manually verify signatures.

To verify signatures, you need to retrieve your endpoint's token from the Dashboard's Webhook settings. To see an endpoint's token, click the Reveal token or Reveal test token button associated with that endpoint.

Each token associated with an endpoint is unique. If you associate a test API key and a live API key with an endpoint, the token for each key is unique. If you use multiple endpoints, you must get the token for each one. When you apply the tokens, Digital River can sign each webhook it sends to the endpoint.

To prevent replay attacks, Digital River includes a timestamp in the DigitalRiver-Signature header. The signed payload has a timestamp that is verified by the signature, so an attacker cannot change the timestamp without invalidating the signature. If the signature is valid, but the timestamp is too old, you can have your application reject the payload.

Each time Digital River sends an event to your endpoint, we generate the timestamp and signature. When your endpoint replied with a non-2xx status code, Digital River will retry the event with a new signature and timestamp.

Event logs

To view the webhook events, sign in to the Dashboard and click Event logs. The Event logs display the event type, event ID, and timestamp for the event.

Event Logs