Event Notifications

The Silverflow API offers agents a mechanism to subscribe to data events and get notifications of these events delivered to an HTTP(S) endpoint operated by the agent. Event notifications hold just enough information to identify the source, the type of event, the subject identifier and a timestamp. The actual event data is not included. To get the corresponding event data an (authenticated) API call should be used to retrieve the entity referenced in the notification. Data Event Subscriptions are managed through the Event Subscriptions endpoint. Event Subscriptions can be created, updated and archived. Once any of these operations have been completed successfully, a test event will be sent to the target URL provided.

In an effort to standardise event exchange and improve interoperability between event producers and consumers the CloudEvents initiative has defined a specification for event description. Silverflow uses the CloudEvent envelope for event notification delivery. The listing below shows a sample event notification:

When an event subscription has been created, modified or deleted, a test event will be sent directly to the target URL provided in the request. The listing below shows a sample test event notification:

Over time the payload of event notifications may change to support new functionality. The API identifies two types of changes: breaking and non-breaking changes. Non-breaking changes are additions to the payload. As with all API responses these may be added at any time without prior notice. Clients must be able to handle these additions without breaking. Breaking changes are changes to either the structure or the existing attribute names. These changes will break existing clients and would require them to implement the changes. To ensure reliable event delivery and processing on the client side, an Event Subscription will always receive event notifications in the version it had when creating the Event Subscription. Updating an Event Subscription, changing the description or the targetUrl attributes will not change the version. However, new Event Subscriptions will always automatically get the latest version of the event notification. This version cannot be changed after creation.

The Silverflow platform supports several sources for event notifications. Please see the API Reference for the most up to date list of event sources.

The Silverflow platform sends the following events from the https://silverflow.com/reconciliation source:

Example com.silverflow.reconciliation.detailBatch event:

Example com.silverflow.reconciliation.dailySettlementTotal event:

Example com.silverflow.reconciliation.reconciliationCycleEnd Mastercard event:

Example com.silverflow.reconciliation.reconciliationCycleEnd Visa event:

Example com.silverflow.reconciliation.networkFundsTransferCompleted Visa event:

The Silverflow platform sends the following events from the https://silverflow.com/currencyRates source:

Example com.silverflow.currencyRates.update event:

The Silverflow platform sends the following events from the https://silverflow.com/fraudNotifications source:

Example com.silverflow.fraudNotification.received event:

The Silverflow platform sends the following events from the https://silverflow.com/clearing source:

Example com.silverflow.clearing.offlineRefundOutcome event:

Event notifications will be delivered to the agent-operated HTTP(S) endpoint specified by target URL of the corresponding Event Subscription. The delivery request uses the following settings:

Below is a sample request that the target URL must process:

The delivery is considered successful if an HTTP response with status code in the 2xx range is received.

Any returned HTTP status code outside of the 2xx success range (so 4xx and 5xx), connection timeout (30 seconds) or connection failure are considered a delivery failure. When a delivery fails the event notification will be rescheduled for delivery. Rescheduling uses an incremental backoff algorithm to determine the next delivery time. The first delay is 60 seconds. The following retries are double that of the preceding with a maximum of 12 hours. Notifications will be attempted to be delivered a total of 36 times over a period of roughly 320 hours. When the message cannot be delivered successfully within this timeframe it will be discarded.

Each event notification will be delivered at least once. Under certain (rare) conditions a single event notification may be delivered more than once.If unique events are required they can be deduplicated using their event.id attribute.

Event notifications, including notifications for a single entity, may be delivered out of sequence. Event notifications may be re-ordered using their event.time attribute.

The event notification delivery is an asynchronous process. When retrieving the entity referenced in the event notification through the API the entity may already have changed. This may or may not be a problem depending on the use case. To verify that the received event notification still applies to the entity retrieved through the API the event.data.version and event.data.lastModified properties of the event notification can be compared with the entity.version and entity.lastModified of the retrieved entity. Action can be taken accordingly.

As described earlier, the event notification is just a notification about an event. The notification itself does not contain any sensitive data and consists solely of meta data and opaque identifiers. The notification should be used as a trigger to fetch the actual referenced data though the Silverflow API. This subsequent call requires the client to authenticate itself to the API using regular authentication means.

Event notification only support TLS client certificate for authentication. Which means the subscription endpoint must be HTTPS to support mutual TLS authentication. So it's strongly recommended using HTTPS as subscription endpoint. When creating an Event Subscription through the API, Silverflow does not check if the target url exists, accepts callbacks or is owned/operated by the agent. All Silverflow's event notification certificate is signed by a well known certificate authority, DigiCert, and to identify the Silverflow event notification certificate you should add the DigiCert's certificate to the known certificate authority in your server configuration. The public certificate from DigiCert can be download from their site. The event delivery is with the following CN (common name) in the certificate, which you can authenticate with:
SBX Environment CN=event-delivery.sbx.silverflow.comPRD Environment CN=event-delivery.silverflow.com

Event notification delivery does not use static IP addresses. It is therefore not possible to restrict access to client endpoints using IP filtering.