Data syncing

Syncing your app data with WorkOS is done using events. Events represent activity that has occurred within WorkOS or within third-party identity and directory providers that interact with WorkOS.

When important activity occurs, we record an event. For example, a new SSO connection being activated is an event. A user being created, assigned membership to an organization, or successfully signing in are all events as well. Events are activity that your application might be interested in for the purposes of syncing data or extending your application’s business logic.

Your app can consume events from WorkOS via either the events API or webhooks.

{
  "object": "event",
  "id": "event_07FKJ843CVE8F7BXQSPFH0M53V",
  "event": "dsync.user.updated",
  "data": {
    "id": "directory_user_01E1X1B89NH8Z3SDFJR4H7RGX7",
    "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
    "organization_id": "org_01EZTR6WYX1A0DSE2CYMGXQ24Y",
    "idp_id": "8931",
    "first_name": "Lela",
    "last_name": "Block",
    "name": "Lela Block",
    "email": "lela.block@example.com",
    "state": "active",
    "created_at": "2021-06-25T19:07:33.155Z",
    "updated_at": "2021-06-25T19:07:33.155Z",
    "custom_attributes": {
      "department": "Engineering",
      "job_title": "Software Engineer"
    },
    "role": { "slug": "member" }
  },
  "created_at": "2023-04-28 20:05:31.093"
}

With the events API, your application retrieves events from WorkOS. The events API offers a more robust data synchronization solution compared to webhooks, ensuring seamless synchronization of your system state with WorkOS. To sync data using the events API, continue to the events API guide.

With webhooks, WorkOS automatically notifies your app when an event occurs by invoking an endpoint hosted within your application. To sync data using webhooks, continue to the webhooks guide.

With the WorkOS sync engine, your WorkOS data is mirrored into a Postgres database you control, so you can query it with SQL and join it to your own application data. The engine combines the events API for live changes, the list endpoints for historical data, and a reconciliation step that detects drift, so you do not have to build and operate that pipeline yourself. To mirror your data into Postgres, continue to the Postgres sync guide.

We recommend using the Events API instead of webhooks to keep your data in sync – especially for user and directory events. With the Events API, you control how often and how much data you ingest. Webhooks, on the other hand, require your endpoint to handle unpredictable spikes in event volume, which can make them harder to manage at scale. That said, webhooks may still be the better fit depending on your use case. If you want the result in your own database rather than in your own event handler, the sync engine builds on the Events API and adds backfill and reconciliation. Here’s how the options compare: