Events

Learn about the structure of events and when they are created.

When something noteworthy happens in your account, we create an event. More specifically, an event is created when the state of another API resource changes. Your integration can use these events to listen for and handle important updates in your account.

In the Digital River APIs, there are numerous event types that you can subscribe to. There are, however, certain key event types that we recommend every integration monitors.

In nearly all cases, an event's data contains the resource whose state changed.

You can also subscribe to expanded events, which contain more data.

To subscribe to an event, you need to set up webhooks that send designated events directly to an endpoint on your server. The Digital River Dashboard contains a complete list of our supported event types. To access this list, create a webhook or view the details of an existing webhook.

You can also use the Events API to return a list of events or retrieve an individual event.‌

Event types

Events use the following naming convention: resource.event.

The event's type usually reflects the current state of that resource. For example, when an order's state moves to accepted, we create an event whose type is order.accepted and when an invoice becomes uncollectible, we create an event whose type is invoice.uncollectible.

Event

{
    "id": "86976837-18b5-473c-9a2e-7e774a827670",
    "type": "order.accepted",
    "data": {
        "object": {
            "id": "247468780336",
            ...
            "state": "accepted",
            ...
        }
    },
    ...
}

There are, however, certain exceptions. For example, an event with a type of subscription.extended indicates that the subscription's state remains active. And even though checkouts don't contain a state attribute, you can listen for checkout.created, checkout.updated, and checkout.deleted events.

When an event occurs on a sub-resource, such as those with a type of order.charge.cancelled, the parent resource's state update event is not activated.

Some API requests trigger multiple events. For example, when a subscription is created, two event types, subscription.created and checkout.created, are emitted.

Event data

An event's data.object typically contains the resource that changed.

Here are a couple of examples: (1) the data.object of an event with a type of order.blocked is an order whose state is blocked and (2) the data.object of an event with a type of order.charge.capture.complete is a charge that contains a capture whose state is complete.

In a few cases, however, this pattern isn't strictly followed. For example, the data.object of a fulfillment_order.shipped contains a shipment resource and the payload of subscription.reminder is both a subscription and an invoice.

An event's data.previousAttributes lists the resource's attributes that changed, along with the previous values of these attributes.‌