Events API

Keep your app in sync with WorkOS.

Introduction

Events represent actions performed within WorkOS, identity, and directory providers. When an action occurs, we record an event. For example, an action could mean an IT admin assigning a user to your app or modifying a user group assigned to your app. These actions are most often performed as part of routine IT Admin workflows.

Your app can interface with WorkOS and retrieve these events using the Events API. The Events API offers a robust data synchronization solution compared to webhooks, ensuring seamless synchronization of your system state with WorkOS.

The Events API returns events up to 30 days old.

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": "veda@foo-corp.com"
      }
    ],
    "first_name": "Lela",
    "ast_name": "Block",
    "job_title": "Software Engineer",
    "username": "veda@foo-corp.com",
    "state": "active",
    "created_at": "2021-06-25T19:07:33.155Z",
    "updated_at": "2021-06-25T19:07:33.155Z",
    "custom_attributes": {
      "department": "Engineering"
    },
    "raw_attributes": {}
  },
  "created_at": "2023-04-28 20:05:31.093"
}

Events API vs. Webhooks

Here are some benefits of using the Events API:

Replayable: The Events API is replayable. You can go back to a specific point in time and reprocess events as needed.

Ordered & deterministic: The Events API guarantees a consistent sequential order. In contrast, webhooks may not be delivered in sequence.

Flexible processing: With the Events API, you can process events at your own pace, reducing the overall number of simultaneous requests and minimizing the risk of your app being overwhelmed by a large number of webhooks.

Lower effort security: By using the Events API, you get authentication, confidentiality, and integrity protection by default. No more need to validate webhook signatures or expose a public webhook endpoint.

Webhooks do not guarantee order, may be delayed, and cannot be re-retrieved after delivery. The Events API simplifies data synchronization by providing a consistently ordered stream of WorkOS events to your app.

Quick StartA step by step guide on how to use the Events API

Up next