A step by step guide on how to use the Events API.
In this guide, we will walk through what you will need to build to integrate with the Events API.
This guide will show you how to:
To get the most out of this guide, you’ll need:
WorkOS offers native SDKs in several popular programming languages. Choose a language below to see instructions in your app’s language.
Don't see an SDK you need? Contact us to request an SDK!
To make calls to WorkOS, provide the API key and, in some cases, the client ID. Store these values as managed secrets, such as
WORKOS_CLIENT_ID, and pass them to the SDKs either as environment variables or directly in your app's configuration based on your preferences.
Sign in to your WorkOS account to see code examples pre-filled with your API keys and resource IDs.
Once your app integrates the WorkOS SDK, your app can start consuming events. The first thing to do is pick a starting place to start consuming.
A cursor is a bookmark to track your app’s position in the events data set. The very first Events API call won’t have a cursor. Subsequent requests to WorkOS should include the updated cursor using
after. You will need to update and store your cursor after processing an event.
To migrate from webhooks:
range_startparameter to start consuming events from a specific time.
updated_atfield to avoid overwriting newer data. For more details, refer to the next section.
The Event IDs passed in webhook bodies are the same as those returned by the Events API.
To avoid repeating an update, store the
updated_at timestamp provided by WorkOS for each object. Extract this tag from the data object in the event. If the
updated_at timestamp in the event is newer, update the local state with the latest event data. Otherwise, you can skip processing that event.
Determine the event types you want to consume. Choose the relevant event types that align with your app’s functionality and integration with WorkOS.
Retrieve events from the API using cursor pagination. To fetch the next set of events, provide the ID of the latest processed event in the
In some cases, it may be necessary to go back in time and “replay” events. When designing your app logic to handle events replay – it is important to design your event handling logic in a way that can safely accommodate event replay without undesired effects.
To achieve this, focus on separating your app’s data handlers from transactional business logic like sending emails, communicating to 3rd party APIs, etc. By implementing separate data handling, you can replay events without side effects.
WorkOS recommends processing events synchronously, handling them in the order they occurred.
When resuming event processing, you have two options to pick up where you left off:
Using the latest known cursor: Retrieve the most recent cursor that was successfully processed and use it as the starting point for event resumption.
Using a timestamp: Alternatively, you can make an API call with the
range_start parameter and then use the cursor. Utilize the
updated_at timestamp to prevent overwrites.
WorkOS recommends that your app starts with a single worker. Process events in a separate thread or process from your app’s main execution thread. Deploying a single worker responsible for handling events simplifies and streamlines event consumption.
This approach ensures serial event processing. After completing the processing of events on the current page, request the next page of events to maintain progress.
For onboarding large organizations, divide events into independent queues for parallel processing when calling the Events API from a single worker.
Concurrently processing events from different organizations is safe, but for consistency and integrity, it is recommended to sequentially process events within a single organization.