Event Notifications

The Silverflow API offers agents a mechanism to subscribe to data events and get notifications delivered to an HTTP(S) endpoint the agent operates. Event notifications provide enough information to identify the source, type of event, subject identifier, and timestamp. The actual event data is not included. To obtain the event data, an authenticated API call must be made to retrieve the referenced entity. Event subscriptions are managed through the Event Subscriptions endpoint, where they can be created, updated, and archived. Once these operations are completed, a test event will be sent to the provided target URL.

Silverflow uses the CloudEvents specification for event notification delivery to standardize event exchange and improve interoperability. Below is 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:

The payload of event notifications may change over time to support new functionality. The API identifies two types of changes: breaking and non-breaking changes. Non-breaking changes are additions to the payload that clients must handle without breaking. Breaking changes affects the structure or existing attribute names and will break existing clients, requiring them to implement changes. Event Subscriptions will always receive notifications in the version used when creating the subscription. Updating an Event Subscription will not change the version, but new subscriptions will automatically use the latest version.

Silverflow supports several sources for event notifications. Please look at 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:

Example com.silverflow.clearing.abandoned event:

The following fields may also be in the response: transactionReference and actionReference.

Following the Abandoned event notification, it is advised to reverse the authorization using Silverflow's charges/{chargeKey}/cancel endpoint. This may limit costs incurred due to authorized transactions that have yet to be cleared.

Event notifications will be delivered to the agent-operated HTTP(S) endpoint specified by the 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 successful if an HTTP response with a status code in the 2xx range is received.

Any returned HTTP status code outside the 2xx success range (4xx and 5xx), connection timeout (30 seconds), or connection failure is 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 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.

Event notification delivery is an asynchronous process. When retrieving the entity referenced in the event notification through the API, the entity may have already 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. It does not contain sensitive data and consists solely of metadata and opaque identifiers. The notification should be used as a trigger to fetch the referenced data through the Silverflow API. This subsequent call requires the client to authenticate to the API using regular authentication.

Event notification only supports TLS client certificates for authentication. This means the subscription endpoint must be HTTPS to support mutual TLS authentication. So, it's strongly recommended that HTTPS be used as a 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 certificates are signed by a well-known certificate authority, DigiCert, and to identify the Silverflow event notification certificate, you should add the DigiCert certificate to the known certificate authority in your server configuration. The public certificate from DigiCert can be downloaded 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. Therefore, it is not possible to restrict access to client endpoints using IP filtering.