Getting Started with Real-time Events

Sparkfly's real-time events system allows you to receive immediate notifications about significant activities occurring within the Sparkfly platform. By developing a callback listener, you can process these events in real-time as they occur.

The full API reference for the Events API can be found here: Events API Reference.

Core Concepts

There are three primary concepts to understand when working with Sparkfly's real-time events system: Events, Callbacks, and Subscriptions.

Events

An Event represents a significant activity or change within the Sparkfly platform. Examples of events include the issuance of offers, updates to loyalty enrollments, and transaction completions. Additionally, there are several events related to configuration changes, such as the creation or modification of most Sparkfly entities.

See the sidebar for a list of available event types and their descriptions.

Callbacks

A Callback is a user-defined HTTP endpoint that is designed to receive event notifications. When an event occurs that a callback is subscribed to, Sparkfly will deliver that event to the URL specified in the callback configuration.

Security

The events delivered to your callback endpoint are signed using HMAC with a signing_key that is generated when you create the callback. This signature allows you to verify the authenticity of the incoming requests and ensure that they originate from Sparkfly. It is the responsibility of the callback receiver to validate this signature for each incoming event notification. Invalid or missing signatures should result in the rejection of the request.

Verification of the HMAC signature should be performed as follows:

1. Read the raw body bytes exactly as received. Do not parse, reformat, or reorder keys before verifying.
2. Compute a SHA256 digest using the raw body bytes and the signing_key received when the callback was created.
3. Decode the value from the x-hmac-sha256-signature header from base64.
4. Verify the computed signature against the received signature.
5. If the signatures do not match, reject the request with an appropriate HTTP status code (e.g., 401 Unauthorized).

Subscriptions

A Subscription links a Callback to one or more Events. By creating a subscription, callbacks are registered to receive notifications for specific events.