Data syncing

Keep your app in sync with WorkOS.

Introduction

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.

A sample event

JSON

 {
  "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",
    "emails": [
      {
        "primary": true,
        "type": "work",
        "value": "lela.block@example.com"
      }
    ],
    "first_name": "Lela",
    "last_name": "Block",
    "job_title": "Software Engineer",
    "username": "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"
    },
    "role": { "slug": "member" },
    "raw_attributes": {}
  },
  "created_at": "2023-04-28 20:05:31.093"
}

Sync using the events API

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.

Sync using webhooks

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.

API vs. webhooks

Depending on your constraints, you may want to use the events API or webhooks. Here is a comparison of the two:

Aspect	Events API	Webhooks
Timing	Controlled by your app. Your server can process events at its own pace.	Real-time. Webhooks trigger as soon as an event occurs.
Order	A consistent order is guaranteed.	No guarantee of order on receipt. Events contain timestamps to determine order.
Reconciliation	Replayable. Can go back to a specific point in time and reprocess events.	Failed requests are retried with exponential back-off for up to 3 days.
Security	Authentication, confidentiality, and integrity protection by default.	You must expose a public endpoint and validate webhook signatures.

Sync data using the events APIA step-by-step guide on how to start syncing data using the API

Up next