Skip to main content
Vindicia Knowledge Center

Set Up

Set Up

CashBox Configuration (Subscribing to Push Notifications)

  • Push Notifications are enabled and configured by Vindicia Support.
  • You subscribe to receive push notifications at the Event Class level.
    • The CashBox Push framework supports unlimited merchant push subscriptions for a given Event Class. This allows you to have the same event (or group of events or full class of events) trigger push messages to multiple targets simultaneously, each with its own rules (endpoint, security, retry configuration).
  • For each subscription, provide Support with:
    • Event Class name
    • A list of Events (within the Event Class) for which you have chosen not to receive notifications (that is, have opted out). Leave this blank to receive notifications for all Events in the Class.
  • See Push notification Classes and Events.
    • Endpoint
    • Format (application/JSON or URL-encoded)
    • Retry Options:
      • Count: the number of times you want CashBox to continue retrying HTTP POST calls
      • Interval: the number of seconds between retries.
    • Error Email Address: The email address to receive optional error notification.
    • Username and Password if opting for HTTP Basic Authentication

Testing

All CashBox environments support Push Notifications.

To quickly test or preview what different types of Push event messages will look like after they’re triggered, you can create a fast test URL with services such as:

RequestBin at http://requestb.in/

Setting Up a Listener

Validating Message origin/authenticity

You should ensure the message is authentic (from CashBox and relevant to you) before processing it.

  • You can validate message content and source using a keyed-hash message authentication code (HMAC) approach. Vindicia will provide you with an HMAC key to serve as the shared secret key. The HMAC signature of each message will be present in the notification as a separate name-value pair. To verify the message, you can use any standard approach to generate your own HMAC signature to compare to the one provided by Vindicia. The HMAC signature is generated using the JSON message content, the shared HMAC key, and base64 encoding with SHA256 encryption.
  • For an added layer of security, CashBox also supports HTTP Basic Authentication, giving you greater assurance of the source of push notifications.

Parsing Messages

  • The Push Notification JSON can be sent as either application/JSON or URL-encoded form (in which case, the message must be decoded before use).
  • Generally CashBox Push Notifications will contain:
    • A standard header including the HMAC signature and primary object VID
    • A JSON rendition of the full object associated with the Event Class (e.g. Account class pushes include a full Account object) - this object should contain the same data that would be found if you fetched the object directly via API (using id or VID).
    • In some cases, such as when the event is a change to data (e.g. a new address) the old/pre-change version is also included as its own JSON object within the message.

Indicating Success

  • Your listener should return a response with a 202 status code to indicate successful receipt of the message.
    • Push Notifications do not follow redirects.
    • Any other HTTP status code response will be treated as an error, triggering retry as configured for the subscription. Note - even a 200 is treated as a failure.
  • Your listener should respond within 30 seconds.

Errors and Retries

  • In the event we do not receive a response, or if the HTTP Basic Authentication fails, or if we receive any status code response other than 202, we will treat the message as an error and retry according to the configured rules for the event subscription.
  • Each event subscription can be configured to retry any number of times with a specified interval (in seconds) in between attempts. Each error generates the optional error email notification. If message exhausts its retries, it will be logged as a permanent error in CashBox logs.

Sequence and Volume Considerations

  • We strive to send notifications as soon as possible as events occur, generally sending a notification within one (1) second of event completion. This speed typically ensures that you’ll receive events in order for a particular account, entitlement, or subscription, but it is possible for a large number of actions to occur on a particular object within a short period of time, meaning that the corresponding events may be in transit at the same time and could arrive in a different order. Listener design should account for this by paying attention to the message identifiers and event timestamps to ensure they process information properly.
  • Prepare for a volume corresponding to the size of your customer/subscriber base and the activity of your billing integration. Many events may be triggered by routine batch processing leading to a large volume of Push Notifications being sent at once (e.g. routine batch renewal billing for every customer due on the same day).
  • cURL
  • Java
 
 

For Users

Learn More
For Users

Cashbox Features

Learn More
Cashbox Features
Back to Top