This guide describes event setup and configuration at Galileo and within your own system. It also includes considerations for receiving and prioritizing events, as well as information on event delivery statuses reported by the CST Alerts Log.
## Receiving events
In cooperation with Galileo, you select which events you want to receive, and then for each event, select which fields you want to include in the event message body. In the API reference, the Events API indexes (listed below) show which fields are included by default, and you can request to remove or add fields as desired.
<a href="ref:api-reference-events-api-account-events-index" target="_blank">Account Events Index</a>
<a href="ref:api-reference-events-api-authorization-events-index" target="_blank">Authorization Events Index</a>
<a href="ref:api-reference-events-api-settlement-events-index" target="_blank">Settlement Events Index</a>
<a href="ref:api-reference-events-api-transaction-events-index" target="_blank">Transaction Events Index</a>
In most cases, you receive events only for active accounts. The individual event descriptions specify which events are sent regardless of account status. You can set the MSGDA parameter to send other events regardless of account status.
## Events prioritization
If an event is triggered with high frequency, it may delay the delivery of other event messages. To prioritize other events over the high-frequency event, Galileo can create a secondary queue for the high-frequency event.
For example, you can ask Galileo to create a secondary queue for the <a href="ref:api-reference-events-api-setl" target="_blank">`
SETL: setl`</a> event, which is triggered every time an authorization is settled. Then, the events in the primary queue are delivered before the SETL events when there is a high volume of `
SETL` events. It is also common for Galileo to create a secondary queue for <a href="ref:api-reference-events-api-adj" target="_blank">`
BADJ: adj`</a> events.
## Events with debit or credit amounts
Some transaction events that have an amount field do not explicitly use a negative sign to report a debit amount. For example, <a href="ref:api-reference-events-api-billpay" target="_blank">`
BPAY: billpay`</a> reports a successful bill pay debited from the customer’s account and always has a positive amount in the `
amount` field. For your internal setup, make sure to note whether an event reports a debit or credit amount.
## Events configuration at Galileo
During product configuration, you determine when and how you will receive Events API webhooks from Galileo. The following are components of Events API configuration in Galileo’s system.
**Format for receiving events and sending responses** — Galileo can send you events in JSON format or as form data, and Galileo can receive your response in JSON or XML format. See <a href="ref:api-reference-events-api-about-events-api" target="_blank">About Events API</a> in the API reference for examples.
**URLs for receiving events** — You provide URLs hosted by a server on your system where Galileo will send Events API webhooks. You must provide separate URLs for the CV and Production environments.
**Product parameters for events** — Behavior for some events can be configured with product parameters. Work with your Galileo representative to decide which events you want to receive for each product and when they should be sent.
**Events to enable in CV and Production** — Galileo can enable different events in the CV and Production environments so that you can test an event in CV while disabling it in Production.
**Frequency and maximum count for message retries** — The RETRY parameter controls the maximum number of retries for an event message and the RTRDL parameter controls the delay between attempts. See “Retry” under <a href="ref:api-reference-events-api-about-events-api" target="_blank">About Events API</a> in the API Reference for more information.
## Your operational setup
The following are considerations for handling Events API webhooks in your own system.
**Forwarding events to customers** — Determine whether you will send events to customers and how you will display them.
**Account balance reporting** — The value in the `
open_to_buy` field may cause confusion if you display it to customers. Instead, use the Program API to display transaction history. See the <a href="doc:transaction-history" target="_blank">Transaction History</a> guide for more information about using data sources to display transaction history to customers.
**Reporting and reconciliation** — The datastore that you build with the Events API should not be used to perform reconciliation, run large reports, perform data analysis or build statements. Instead, you should create a separate datastore using the RDFs. See <a href="doc:about-rdfs-and-cdfs#building-a-datastore" target="_blank">Building a datastore</a> in the _About RDFs and CDFs_ guide for more information.
### Transaction event timestamps and account balance
Although you can use event messages to track an account's transaction activity, you cannot use events to determine an account's balance at any given time. Keep in mind the following:
timestamp` in the event body corresponds to the time when the event occurred on the Galileo system, but the `
open_to_buy` was captured later, during the message assembly.
You can add `
opentobuy_ts` to your transaction-related events to see exactly when the `
open_to_buy` was captured.
Event messages will likely not arrive on your system in the same order they were generated. Some events are delayed, and occasionally they do not arrive at all.
You should therefore interpret `
open_to_buy` as being accurate as of `
opentobuy_ts`, not as the result of the reported event.
See <a href="doc:transaction-history" target="_blank">Transaction History</a> for the recommended method to retrieve and present the latest customer data in your interface.
## CST Alerts Log
In the Customer Service Tool, the Alerts Log displays a record of Events API messages that Galileo has sent as a result of activity on an account. The Alerts Log is located in the CST **Account** tab.
The Alerts Log displays the delivery status for each event. This table lists each event delivery status and describes the next step to take.
|Card holder has not opted to receive this alert||None|
|Error||Work with Galileo to determine why the event was not sent.|
|Queued to be sent||None. If there is a high volume of event messages, this message will be sent later. See [Events prioritization](🔗) for information on creating a secondary queue.|
|Product not configured for this msg_id||If you did not expect this event, there is no next step.|
|Alert Processing Not Completed||Work with Galileo to determine why the event was not sent.|
To correlate a transaction with a CST alert, use the alert timestamp.
## Galileo setup
|CDMSG||Product||Specifies which card status updates will trigger the `|
|MSGDA||Product||Specifies which events are triggered regardless of account status. Default:<li>`|
|RETRY||Product||Maximum retries to send a message.|
|RTRDL||Product||Delay in seconds before resending a message. The delay increases exponentially for each retry by multiplying the square of the retry count by RTRDL.|