Respond to activity that occurs within WorkOS and third-party providers.
Events represent activity that has occurred within WorkOS or within third-party identity and directory providers. Your app can sync the data via either the events API or webhooks.
All event objects contain the following attributes:
Attribute | Description |
---|---|
event | Distinguishes the event type. |
id | Unique identifier for the event. |
data | Event payload. Payloads match the corresponding API objects. |
created_at | Timestamp of when the event occurred. |
Triggered when a user is created, updated, or deleted.
{ "event": "user.created", "id": "event_02F4KLW3C56P083X43JQXF4FO9", "data": { "object": "user", "id": "user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E", "email": "todd@example.com", "first_name": "Todd", "last_name": "Rundgren", "email_verified": false, "profile_picture_url": "https://workoscdn.com/images/v1/123abc", "created_at": "2023-11-18T09:18:13.120Z", "updated_at": "2023-11-18T09:18:13.120Z" }, "created_at": "2023-11-18T04:18:13.126Z" }
Triggered when a role is created or deleted.
{ "event": "role.created", "id": "event_02F4KLW3C56P083X43JQXF4FO9", "data": { "object": "role", "slug": "admin", "created_at": "2023-11-16T21:32:25.235Z", "updated_at": "2023-11-16T21:32:25.235Z" }, "created_at": "2023-11-16T21:32:25.245Z" }
Triggered when an organization membership is added, updated, or removed.
{ "event": "organization_membership.added", "id": "event_04FKJ843CVE8F7BXQSPFH0M53V", "data": { "id": "om_01E4ZCR3C56J083X43JQXF3JK5", "object": "organization_membership", "user_id": "user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E", "organization_id": "org_01E4ZCR3C56J083X43JQXF3JK5", "status": "pending", "role": { "slug": "member" }, "created_at": "2023-11-16T21:32:25.235Z", "updated_at": "2023-11-16T21:32:25.235Z" }, "created_at": "2023-11-16T16:32:25.239Z" }
Triggered when a session is created.
Sessions started using impersonation will include an additional impersonator
field with data about the impersonator.
{ "event": "session.created", "id": "event_04FKJ843CVE8F7BXQSPFH0M53V", "data": { "object": "session", "id": "session_01HSCBECW0D7AY8CA45AYKA64G", "user_id": "user_01HQGXWZW8BSHRG3HVK2QF7XBX", "organization_id": "org_01HQHCBRRAVQ7N3PX81VKAYXSX", "impersonator": { "email": "admin@example.com", "reason": "Helping a customer fix an issue with their account." }, "ip_address": "192.0.2.1", "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/94.0.4606.81 Safari/537.36", "created_at": "2024-03-19T21:56:25.080Z", "updated_at": "2024-03-19T21:56:25.080Z" }, "created_at": "2024-03-19T21:56:25.080Z" }
Triggered when an user attempts to authenticate. Each step in the authentication flow emits an authentication event. An authentication attempt is considered successful even if additional steps, such as multi-factor authentication, are required before authentication is completed.
Authentication failed events aren’t emitted yet, but will be available soon.
Triggered when a user attempts to authenticate via Magic Auth.
{ "event": "authentication.magic_auth_succeeded", "id": "event_04FKJ843CVE8F7BXQSPFH0M53V", "data": { "type": "magic_auth", "status": "succeeded", "user_id": "user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E", "email": "todd@example.com", "ip_address": "192.0.2.1", "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/94.0.4606.81 Safari/537.36" }, "created_at": "2023-11-18T04:18:13.126Z" }
Triggered when a user attempts to authenticate via OAuth.
{ "event": "authentication.oauth_succeeded", "id": "event_04FKJ843CVE8F7BXQSPFH0M53V", "data": { "type": "oauth", "status": "succeeded", "user_id": "user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E", "email": "todd@example.com", "ip_address": "192.0.2.1", "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/94.0.4606.81 Safari/537.36" }, "created_at": "2023-11-18T04:18:13.126Z" }
Triggered when a user attempts to authenticate via password.
{ "event": "authentication.password_succeeded", "id": "event_04FKJ843CVE8F7BXQSPFH0M53V", "data": { "type": "password", "status": "succeeded", "user_id": "user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E", "email": "todd@example.com", "ip_address": "192.0.2.1", "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/94.0.4606.81 Safari/537.36" }, "created_at": "2023-11-18T04:18:13.126Z" }
Triggered when a user attempts to authenticate via single sign-on.
{ "event": "authentication.sso_succeeded", "id": "event_04FKJ843CVE8F7BXQSPFH0M53V", "data": { "type": "sso", "status": "succeeded", "user_id": "user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E", "email": "todd@example.com", "ip_address": "192.0.2.1", "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/94.0.4606.81 Safari/537.36" }, "created_at": "2023-11-18T04:18:13.126Z" }
Triggered when a user attempts to continue authentication with an email verification code.
{ "event": "authentication.email_verification_succeeded", "id": "event_04FKJ843CVE8F7BXQSPFH0M53V", "data": { "type": "email_verification", "status": "succeeded", "user_id": "user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E", "email": "todd@example.com", "ip_address": "192.0.2.1", "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/94.0.4606.81 Safari/537.36" }, "created_at": "2023-11-18T04:18:13.126Z" }
Triggered when a user attempts to continue authentication with a multi-factor authentication code.
{ "event": "authentication.mfa_succeeded", "id": "event_04FKJ843CVE8F7BXQSPFH0M53V", "data": { "type": "mfa", "status": "succeeded", "user_id": "user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E", "email": "todd@example.com", "ip_address": "192.0.2.1", "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/94.0.4606.81 Safari/537.36" }, "created_at": "2023-11-18T04:18:13.126Z" }
Triggered when a connection is activated, deactivated, or deleted.
{ "event": "connection.activated", "id": "event_10FKJ843CVE8F7BXQSPFH0M53V", "data": { "object": "connection", "id": "conn_01EHWNC0FCBHZ3BJ7EGKYXK0E6", "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY", "state": "active", "connection_type": "OktaSAML", "name": "Foo Corp's Connection", "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:07:33.155Z", "domains": [ { "id": "conn_domain_01EHWNFTAFCF3CQAE5A9Q0P1YB", "object": "connection_domain", "domain": "foo-corp.com" } ] }, "created_at": "2021-06-25T19:07:33.155Z" }
You can ignore the connection’s state
attribute on connection.deleted
event, since it indicates the state before the deletion occurs.
Refer to the in-depth Directory Sync guide to learn about what exactly each directory-related event represents in relation to the activity that occurs within directory providers.
Triggered when a directory is activated or deleted.
{ "event": "dsync.activated", "id": "event_01FKJ843CVE8F7BXQSPFH0M53V", "data": { "object": "directory", "external_key": "UWuccu6o1E0GqkYs", "name": "Foo Corp's Directory", "organization_id": "org_01EZTR6WYX1A0DSE2CYMGXQ24Y", "id": "directory_01EHWNC0FCBHZ3BJ7EGKYXK0E6", "state": "active", "type": "generic scim v2.0", "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:07:33.155Z", "domains": [ { "object": "organization_domain", "id": "org_domain_01EZTR5N6Y9RQKHK2E9F31KZX6", "domain": "foo-corp.com" } ] }, "created_at": "2021-06-25T19:07:33.155Z" }
When receiving a dsync.deleted
event you can ignore the connection’s state
attribute, since it indicates the state before the deletion occurs.
Triggered when a directory user is created, updated, or deleted.
{ "event": "dsync.user.created", "id": "event_07FKJ843CVE8F7BXQSPFH0M53V", "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" }, "raw_attributes": {} }, "created_at": "2021-06-25T19:07:33.155Z" }
Triggered when a group is created, updated, or deleted. It is also triggered when a user is added or removed from a group.
{ "event": "dsync.group.created", "id": "event_44FKJ843CVE8F7BXQSPFH0M53V", "data": { "id": "directory_group_01E1X5GPMMXF4T1DCERMVEEPVW", "idp_id": "02grqrue4294w24", "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74", "organization_id": "org_01EZTR6WYX1A0DSE2CYMGXQ24Y", "name": "Developers", "created_at": "2021-06-25T19:07:33.155Z", "updated_at": "2021-06-25T19:07:33.155Z", "raw_attributes": {} }, "created_at": "2021-06-25T19:07:33.155Z" }
Triggered when an organization domain is verified or fails verification.
{ "event": "organization_domain.verified", "id": "event_07FKJ843CVE8F7BXQSPFH0M53A", "data": { "object": "organization_domain", "id": "org_domain_01HACSKJ57W8M2Q0N2X759C5HS", "domain": "domain-to-verify.com", "state": "verified", "verification_token": "gBIJgYXZLjW8uHHpz614dkgqm", "verification_strategy": "dns" }, "created_at": "2021-06-25T19:07:33.155Z" }