Webhooks

Learn about the webhooks.

Webhooks are an essential tool for modern applications, allowing for real-time notification of events. Essentially, they operate as user-defined HTTP callbacks triggered by specific events in a service like Digital River. Digital River sends a POST request to the specified endpoint URL when an event occurs, delivering a payload with the event data. This mechanism enables your application to immediately react to various occurrences such as order updates, changes in subscription status, or refunds, ensuring your system stays in sync with the service events. Through the use of webhooks, developers can streamline workflows, enhance user experience, and maintain up-to-date data across systems without the need for polling.

You can use the Webhook Service page in Global Commerce or the Webhooks API to search, create, edit, enable, disable, and delete webhooks. You can also reveal and rotate webhook secrets. When you register your webhook URLs with Digital River, Digital River creates a data object and sends webhook events that notify your application any time an event occurs. The data object includes the type of event and the data associated with that event.

Digital River uses webhooks to notify your application (endpoint URL) when events occur in Global Commerce. A webhook contains the event and timestamp for the event. You can use the Webhooks Service in Global Commerce to search, edit, create, and delete webhooks.

Webhook ID

A Webhook ID is a unique identifier assigned to a specific webhook. This ID is crucial for managing webhooks, allowing precise control over operations such as search, edit, enable, disable, and delete. If you need to locate a particular webhook within Digital River's Global Commerce, knowing its Webhook ID will allow you to search for it directly on the Webhook Service page.

Endpoint URL

An endpoint URL is the destination on your server to which Digital River sends webhook events. It's the URL where you receive and process the data payload from an event. The URL must start with http:// or https:// and be capable of returning a 2xx HTTP status code to acknowledge as an acknowledgment of event receipt. Failure to acknowledge events with a 2xx HTTP status code over several days may result in the endpoint being disabled by Digital River. It is important to properly configure and maintain your endpoint to ensure continuous reception and handling of webhook events.

Secret

A secret is a unique key that Digital River uses to sign the payloads sent to your endpoint URL. This signature ensures the integrity and security of the data, confirming that the payload has not been tampered with in transit. You can view and change a webhook's secret from your account settings. Using this secret in your endpoint's verification process is crucial for confirming the authenticity of the received payloads.

You can reveal and rotate a webhook's secret in Global Commerce.

Security practices for webhook data transmission

To ensure the confidentiality and integrity of the data transmitted via webhooks, consider the following practices:

1. Use HTTPS: Always use HTTPS for your endpoint URLs to ensure that data in transit is encrypted.

2. Validate payload signatures: Implement payload signature verification using the secret provided by Digital River. This confirms the data has not been altered.

3. Limit retries: To prevent denial-of-service (DoS) attacks, configure your server to limit retry attempts after unsuccessful deliveries.

4. IP Safelisting: If possible, safelist the IP addresses from which the webhooks originate to ensure you only accept incoming requests from trusted sources.

5. Logging and monitoring: Keep detailed logs of incoming webhook traffic and monitor for unusual patterns or failed verification attempts.

6. Review and rotate secrets regularly: Review and rotate your webhook secrets in Global Commerce to minimize the risk of unauthorized access.

By adhering to these security practices, you can significantly enhance the safety and reliability of your webhook integrations.

Status

The status of a webhook indicates whether it is active and capable of sending or receiving data payloads. By default, the status is disabled, meaning no events will trigger payloads to be sent to the specified endpoint. You can enable a webhook upon creation or change its status manually anytime afterward.

Enabling a webhook is straightforward and does not require additional confirmation. However, to manually disable a webhook, you must confirm this action by entering your case-sensitive username. This safeguard helps prevent accidental or unauthorized changes to your webhook's operational status.