Exchanging Events

info

If you are using the Sender and Receiver Clients, you can skip this section.

Consuming API Endpoints

All endpoint calls need an JWT Bearer token provided in the HTTP Header (see Authentication). The token is obtained from the token endpoint and is valid for 60 minutes, so we recommend caching this token and re-using it until it nears expiration, before fetching a new token. The diagram below shows a common flow for endpoint calls.

Receiving (Inbound) Events

Inbound events must be polled from the events endpoint. Multiple events can be retrieved at once, but you must send back an ACK for each event in ascending sequence to indicate you have received it. You might decide to process each event one at a time immediately, or save them to your own internal queue or staging table, and process them later. Without sending the ACK to IAS API, we would send you back the same event forever until it's "acknowledged". You cannot skip events, you have to ACK back the events in the same order you receive them. This is why we recommend an intermediate staging table to hold all the events in your own infrastruture, because then you can skip and replay events as needed.

Below is a sequence diagram of a possible polling service that is continuously running (idle). Every X minutes, the service could receives a wake up trigger to fetch and process all inbound sis events. The diagram has two loops, one that keeps checking for the next batch of 100 events, and an inner loop that processes each event, making sure to send back the ACK when done.

In the loop as you process events it will be important to perform an idempotence check to ensure you have not already processed the event (based on the event's unique identifier). This will handle the unexpected case where a given event is already processed in your system but there is a service interruption that prevents the Acknowledgement from reaching IAS.