Event Notifications

A key benefit of the Silverflow platform is the depth of data it can provide. However, in some cases, an agent may want to receive this data asynchronously in the form of events to accommodate a specific system architecture. For this purpose, the Silverflow API is equipped with a notification system to inform agents about selected events via an HTTP(S) webhook. An agent can sign up to receive these notifications using an event subscription, which can be created and managed using the Event Subscription API.

After creating a subscription, the Silverflow platform will send a test event to the specified webhook to verify that everything has been set up correctly. Then, the agent can begin to receive notifications. Importantly, these notifications don’t include any data. Instead, they specify the event source, event type, subject identifier(s), and some additional metadata. The agent can use the subject identifier(s) to retrieve any further data using the appropriate API endpoints.

Event notifications use the JSON format and follow the CloudEvents specification. Find an example below:

The data property contains additional information required to retrieve the event data, and will change for different events. In particular, expect the following structure as test notification when creating or deleting an event subscription:

The notification payload may change over time to accommodate the continuous evolution of the Silverflow platform. To differentiate notification versions, the dataschema property includes a version indicator. Non-breaking changes, identified by the minor version, may be applied automatically to existing subscriptions. Usually, this is limited to the addition of new fields. Consumers are expected to handle these changes correctly.

Breaking changes affect the event structure or modify existing properties. They require an update of the agent’s implementation, and are indicated by the major version. Existing event subscriptions are unaffected by these changes. If an agent desires the latest major version of an event, they must create a new subscription.

Event notifications are sent to the specified HTTP(S) webhook using the POST method and content type application/json. Each notification will be delivered at least once. Under rare circumstances, a single notification might be delivered more than once. To avoid re-processing them, the id property can be used as a deduplication key.

Furthermore, the event delivery is asynchronous. Notifications may be delivered out of their chronological sequence. This also means that data entities referenced in the notification may have changed by the time of retrieval. In both cases, the time property can be used to reconstruct the order of operations.

The delivery system expects a 2xx HTTP response code upon sending a notification. In any other case, it is considered a failed delivery. This includes the following scenarios:

Silverflow will re-attempt any failed deliveries using an incremental back-off algorithm with an initial delay of 60 seconds. Delivery is retried for a total of 36 times, doubling the delivery delay each time to a maximum of 12 hours. Afterward, the notification will be discarded.

Redirects
The delivery system will follow HTTP redirects (i.e., response codes 301, 302, 303, 307, 308) for a maximum of 5 times. Afterward, it is considered a failed delivery.

The only form of authentication supported for notification webhooks are TLS client certificates. This feature is only available when using HTTPS, which is strongly recommended. Silverflow’s event notification certificates are signed by DigiCert. To verify them, add DigiCert’s public certificate to the agent’s list of known certificate authorities.

Silverflow uses the following CN (common name) in their certificates, which can be used to authenticate incoming requests:

Dynamic IP Addresses
The notification delivery system uses dynamic IP addresses. Therefore, it is not possible to restrict access to webhooks using IP filtering.

When creating an event subscription, the agent can select a single event source they want to receive notifications from, which can be updated later on. However, every event source may publish multiple event types (indicated by the event’s type property), each coming with its own, versioned data schema (i.e., dataschema property).

While the event type cannot be configured on the event subscription directly, agents can filter incoming events based on their respective properties. The data schemas for each event type are determined when creating the event subscription, and usually upgrade minor versions automatically. Major versions and some rare minor versions cannot be changed and require a new event subscription. These changes will be communicated by Silverflow directly.

Currently, the Silverflow platform supports 12 different event sources. Find a small summary for every notification type below:

The following events are sent by the https://silverflow.com/charges event source:

The following events are sent by the https://silverflow.com/disputes event source:

The following events are sent by the https://silverflow.com/documents event source:

The following events are sent by the https://silverflow.com/reconciliation event source:

The following events are sent by the https://silverflow.com/complianceCases event source:

The following events are sent by the https://silverflow.com/currencyRates event source:

The following events are sent by the https://silverflow.com/fraudNotifications event source:

The following events are sent by the https://silverflow.com/clearing event source:

The following events are sent by the https://silverflow.com/networkTokens event source:

The following events are sent by the https://silverflow.com/reports event source:

The following events are sent by the https://silverflow.com/processorTokens event source: