Events
Events API provides a way to listen for events of interest as they relate to your program. For example, you may want to listen for Account status changes or Transactions as they occur.
There are two approaches to consume events, traditional poll request and event streaming using Server-Sent Events. You might first want to consider the approach that best suits your architecture.
Poll Events
A standard request to GET /events
will trigger the polling mechanism to fetch events based on the filters provided. This
is standard request/response flow. The endpoint will hold the connection until either event(s) are returned or a timeout
has occurred. The timeout is random but is at a maximum 1-minute long.
The response will contain the last_sequence_number
in the event list which can be used in a subsequent request.
GET /events
Response:
{
"data": [
{
"id": "c773c2bb-be73-4400-889c-df823ebc849e",
"program_id": "cf2d36e4-68cc-4b10-9dd5-17ac5e07d60f",
"sequence_number": 1,
"created_dt": "2022-01-02T03:04:05.123456-05:00",
"type": "PROFILE_ACCOUNT_STATUS",
"data": {
"id": "2c52e04d-9688-4b9c-be4a-87468b2cb2e8",
"profile_ids": [
"f54e01b2-1cde-4ea5-b6ba-0b8031d3b1ad"
],
"name": "Basic Checking",
"status": "PENDING",
"blockchain_address": "tp180pfr6g45upsrta04l2xd8v08x9jntljgx0gzu",
"account_number_last_four": "1234",
"routing_number": "000000000",
"created_dt": "2022-01-01T01:00:00.123456-05:00",
"updated_dt": "2022-01-02T03:04:05.123456-05:00"
}
}
],
"last_sequence_number": 1,
"limit": 100
}
Stream Events
Using the event stream endpoint, you can listen for events as they unfold in real-time. The endpoint returns events matching
the criteria provided and sends events using the
Server-Sent Events (SSE)
standard once a connection has been established. This requires setting the Accept
header to text/event-stream
.
Sample CURL Request
curl -X GET https://api.test.figurepay.com/events/stream \
-H 'Accept: text/event-stream' \
-H 'Authorization: Bearer <access_token>'
Response
id: 1
data: [{"id":"c773c2bb-be73-4400-889c-df823ebc849e","type":"PROFILE_ACCOUNT_STATUS","program_id":"cf2d36e4-68cc-4b10-9dd5-17ac5e07d60f","sequence_number":"1","created_dt":"2022-01-02T03:04:05.123456-05:00","data":{"id": "2c52e04d-9688-4b9c-be4a-87468b2cb2e8","profile_ids": ["f54e01b2-1cde-4ea5-b6ba-0b8031d3b1ad"],"name": "Basic Checking","status": "PENDING","blockchain_address": "tp180pfr6g45upsrta04l2xd8v08x9jntljgx0gzu","account_number_last_four": "1234","routing_number": "000000000","created_dt": "2022-01-01T01:00:00.123456-05:00","updated_dt": "2022-01-02T03:04:05.123456-05:00"}}]
Here the id
is treated as the last_sequence_number
. If the connection fails or is complete, you can use this to set your starting point.
Retrieve a single event
Fetch a single event by either its id
or sequence_number
for the authenticated program.
GET /event/:id
GET /event/sequence/:sequence_number
Event Types
Every event has a data
field with contents related to the specific event type. This is a list of all current event types.
This list is subject to be updated as more types may be added.
Type | Description |
---|---|
card_changed | Card was inserted or updated |
card_status | Card status was changed |
invoice_changed | Invoice was inserted or updated |
invoice_status | Invoice status was changed |
profile_changed | Profile was inserted or updated |
profile_status | Profile status was changed |
profile_account_changed | Profile account was inserted or updated |
profile_account_status | Profile account status was changed |
program_account_changed | Program account was inserted or updated |
program_account_status | Program account status was changed |
transaction_changed | Transaction was inserted or updated |
transaction_status | Transaction status was changed |
The data model that corresponds with each model type is the full model definition of that object irrespective of if the event is for a
_changed
event or a _status
event. The _status
events are a subset of the _changed
events given that they are only emitted when
the status is first set or updated, whereas any change will emit a _changed
event.