WorkOS Docs Homepage
Events
API referenceDashboardSign In
Event typesEvent typesData syncingOverviewOverviewSyncing with events APISyncing with events APISyncing with webhooksSyncing with webhooksData reconciliationData reconciliationObservabilityStreaming to DatadogStreaming to Datadog
API Reference
API Reference
Integrations
Integrations
Migrate to WorkOS
Migrate to WorkOS
SDKs
SDKs

Events

Respond to activity that occurs within WorkOS and third-party providers.

On this page

  • Authentication events
  • Connection events
  • Directory Sync events
  • Email verification events
  • Invitation events
  • Magic Auth events
  • Organization events
  • Organization domain events
  • Organization membership events
  • Password reset events
  • Role events
  • Session events
  • User events

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.

Event object

All event objects share a similar structure.

AttributeDescription
eventA string that distinguishes the event type.
idUnique identifier for the event.
dataEvent payload. Payloads match the corresponding API objects.
created_atTimestamp of when the event occurred.

Authentication events

Each step in the authentication flow emits an authentication event. Authentication success events are emitted even when additional steps, such as MFA, are required to complete the process.

Email verification failed event
JSON
{
"event": "authentication.email_verification_failed",
"id": "event_04FKJ843CVE8F7BXQSPFH0M53V",
"data": {
"type": "email_verification",
"status": "failed",
"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",
"error": {
"code": "invalid_one_time_code",
"message": "Invalid one-time code"
}
},
"created_at": "2023-11-18T04:18:13.126Z"
}

Triggered when a user fails to verify their email.

Email verification succeeded event
JSON
{
"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 successfully verifies their email.

Magic Auth failed event
JSON
{
"event": "authentication.magic_auth_failed",
"id": "event_04FKJ843CVE8F7BXQSPFH0M53V",
"data": {
"type": "magic_auth",
"status": "failed",
"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",
"error": {
"code": "authentication_method_not_allowed",
"message": "Google OAuth is disabled."
}
},
"created_at": "2023-11-18T04:18:13.126Z"
}

Triggered when a user fails to authenticate via Magic Auth.

Magic Auth succeeded event
JSON
{
"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 successfully authenticates via Magic Auth.

MFA failed event
JSON
{
"event": "authentication.mfa_failed",
"id": "event_04FKJ843CVE8F7BXQSPFH0M53V",
"data": {
"type": "mfa",
"status": "failed",
"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",
"error": {
"code": "invalid_one_time_code",
"message": "Invalid one-time code."
}
},
"created_at": "2023-11-18T04:18:13.126Z"
}

Triggered when a user fails to authenticate with a multi-factor authentication code.

MFA succeeded event
JSON
{
"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 user successfully authenticates with a multi-factor authentication code.

OAuth failed event
JSON
{
"event": "authentication.oauth_failed",
"id": "event_04FKJ843CVE8F7BXQSPFH0M53V",
"data": {
"type": "oauth",
"status": "failed",
"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",
"error": {
"code": "invalid_credentials",
"message": "Invalid credentials."
}
},
"created_at": "2023-11-18T04:18:13.126Z"
}

Triggered when a user fails to authenticate via OAuth.

OAuth succeeded event
JSON
{
"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 successfully authenticates via OAuth.

Password authentication failed event
JSON
{
"event": "authentication.password_failed",
"id": "event_04FKJ843CVE8F7BXQSPFH0M53V",
"data": {
"type": "password",
"status": "failed",
"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",
"error": {
"code": "invalid_credentials",
"message": "Invalid credentials."
}
},
"created_at": "2023-11-18T04:18:13.126Z"
}

Triggered when a user fails to authenticate with password credentials.

Password authentication succeeded event
JSON
{
"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 successfully authenticates with password credentials.

SSO failed event
JSON
{
"event": "authentication.sso_failed",
"id": "event_04FKJ843CVE8F7BXQSPFH0M53V",
"data": {
"type": "sso",
"status": "failed",
"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",
"error": {
"code": "authentication_method_not_allowed",
"message": "SSO is disabled for this environment."
}
},
"created_at": "2023-11-18T04:18:13.126Z"
}

Triggered when a user fails to authenticate with Single Sign-On.

SSO succeeded event
JSON
{
"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 successfully authenticates with Single Sign-On.

Radar risk detected event
JSON
{
"event": "authentication.radar_risk_detected",
"id": "event_04FKJ843CVE8F7BXQSPFH0M53V",
"data": {
"auth_method": "magic_auth",
"action": "signup",
"control": "restriction",
"blocklist_type": "ip_address",
"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",
"user_id": "user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E"
},
"created_at": "2023-11-18T04:18:13.126Z"
}

Triggered when an authentication succeeds but is flagged by Radar. For example, the authentication may have succeeded at passing a Radar challenge.

Connection events

Events emitted when Single Sign-On connections are activated, deactivated, or deleted.

Connection activated event
JSON
{
"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": "org_domain_01EHWNFTAFCF3CQAE5A9Q0P1YB",
"object": "connection_domain",
"domain": "foo-corp.com"
}
]
},
"created_at": "2021-06-25T19:07:33.155Z"
}

Payload data corresponds to the Connection object.

Triggered when a connection is activated.

Connection deactivated event
JSON
{
"event": "connection.deactivated",
"id": "event_11FKJ843CVE8F7BXQSPFH0M53V",
"data": {
"object": "connection",
"id": "conn_01EHWNC0FCBHZ3BJ7EGKYXK0E6",
"organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
"state": "inactive",
"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": "org_domain_01EHWNFTAFCF3CQAE5A9Q0P1YB",
"object": "connection_domain",
"domain": "foo-corp.com"
}
]
},
"created_at": "2021-06-25T19:07:33.155Z"
}

Payload data corresponds to the Connection object.

Triggered when a connection is deactivated.

Connection deleted event
JSON
{
"event": "connection.deleted",
"id": "event_12FKJ843CVE8F7BXQSPFH0M53V",
"data": {
"object": "connection",
"id": "conn_01EHWNC0FCBHZ3BJ7EGKYXK0E6",
"organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
"state": "inactive",
"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": "org_domain_01EHWNFTAFCF3CQAE5A9Q0P1YB",
"object": "connection_domain",
"domain": "foo-corp.com"
}
]
},
"created_at": "2021-06-25T19:07:33.155Z"
}

Payload data corresponds to the Connection object.

Triggered when a connection is deleted. The state attribute indicates connection state before deletion.

Directory Sync events

Events emitted when directory-related resources are changed. To learn what exactly each of these events represents, see the in-depth Directory Sync events guide.

Directory activated event
JSON
{
"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"
}

Payload data is based on the Directory object, but the domain property is replaced with a domains array of Organization Domain.

Triggered when a directory is activated.

Directory deleted event
JSON
{
"event": "dsync.deleted",
"id": "event_03FKJ843CVE8F7BXQSPFH0M53V",
"data": {
"object": "directory",
"id": "directory_01EHWNC0FCBHZ3BJ7EGKYXK0E6",
"organization_id": "org_01EZTR6WYX1A0DSE2CYMGXQ24Y",
"type": "generic scim v2.0",
"state": "deleting",
"name": "Foo Corp's Directory",
"created_at": "2021-06-25T19:07:33.155Z",
"updated_at": "2021-06-25T19:07:33.155Z"
},
"created_at": "2021-06-25T19:07:33.155Z"
}

Payload data is based on the Directory object, except the domain property is omitted.

Triggered when a directory is deleted. The state attribute indicates directory state before deletion.

Directory group created event
JSON
{
"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"
}

Payload data corresponds to the Directory Group object.

Triggered when a directory group is created.

Directory group deleted event
JSON
{
"event": "dsync.group.deleted",
"id": "event_06FKJ843CVE8F7BXQSPFH0M53V",
"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"
}

Payload data corresponds to the Directory Group object.

Triggered when a directory group is deleted.

Directory group updated event
JSON
{
"event": "dsync.group.updated",
"id": "event_54FKJ843CVE8F7BXQSPFH0M53V",
"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": {},
"previous_attributes": {}
},
"created_at": "2021-06-25T19:07:33.155Z"
}

Payload data corresponds to the Directory Group object.

Triggered when a directory group is updated.

Directory group user added event
JSON
{
"event": "dsync.group.user_added",
"id": "event_04FKJ843CVE8F7BXQSPFH0M53V",
"data": {
"directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
"user": {
"id": "directory_user_01E1X56GH84T3FB41SD6PZGDBX",
"directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
"organization_id": "org_01EZTR6WYX1A0DSE2CYMGXQ24Y",
"idp_id": "2936",
"emails": [
{
"primary": true,
"type": "work",
"value": "eric@example.com"
}
],
"first_name": "Eric",
"last_name": "Schneider",
"username": "eric@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" },
"raw_attributes": {}
},
"group": {
"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"
}

Payload data contains a user which corresponds to the Directory User object and a group which corresponds to the Directory Group object.

Triggered when a directory group user is added.

Directory group user removed event
JSON
{
"event": "dsync.group.user_removed",
"id": "event_05FKJ843CVE8F7BXQSPFH0M53V",
"data": {
"directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
"user": {
"id": "directory_user_01E1X56GH84T3FB41SD6PZGDBX",
"directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
"organization_id": "org_01EZTR6WYX1A0DSE2CYMGXQ24Y",
"idp_id": "2936",
"emails": [
{
"primary": true,
"type": "work",
"value": "eric@example.com"
}
],
"first_name": "Eric",
"last_name": "Schneider",
"username": "eric@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" },
"raw_attributes": {}
},
"group": {
"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"
}

Payload data contains a user which corresponds to the Directory User object and a group which corresponds to the Directory Group object.

Triggered when a directory group user is removed.

Directory user created event
JSON
{
"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",
"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",
"job_title": "Software Engineer"
},
"role": { "slug": "member" },
"raw_attributes": {}
},
"created_at": "2021-06-25T19:07:33.155Z"
}

Payload data corresponds to the Directory User object.

Triggered when a directory user is created.

Directory user deleted event
JSON
{
"event": "dsync.user.deleted",
"id": "event_09FKJ843CVE8F7BXQSPFH0M53V",
"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": "inactive",
"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": "2021-06-25T19:07:33.155Z"
}

Payload data corresponds to the Directory User object.

Triggered when a directory user is deleted. The state attribute indicates directory user state at time of deletion.

Directory user updated event
JSON
{
"event": "dsync.user.updated",
"id": "event_08FKJ843CVE8F7BXQSPFH0M53V",
"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",
"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",
"job_title": "Software Engineer"
},
"role": { "slug": "member" },
"raw_attributes": {},
"previous_attributes": {}
},
"created_at": "2021-06-25T19:07:33.155Z"
}

Payload data corresponds to the Directory User object.

Triggered when a directory user is updated.

Email verification events

Events emitted when a user is required to verify their email.

Email verification created event
JSON
{
"event": "email_verification.created",
"id": "event_01HYGAQ6DVKP4TKDF8P8AHFP47",
"data": {
"object": "email_verification",
"id": "email_verification_01HYGAQN7DTHPWDDMMTW6GRN4Z",
"user_id": "user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E",
"email": "todd@example.com",
"expires_at": "2023-11-16T21:32:25.235Z",
"created_at": "2023-11-16T21:32:25.235Z",
"updated_at": "2023-11-16T21:32:25.235Z"
},
"created_at": "2023-11-16T16:32:25.239Z"
}

Payload data corresponds to the Email verification object with the code omitted.

Triggered when a user is required to verify their email and a code is created.

Invitation events

Events emitted when a User Management user is invited to join an organization.

Invitation created event
JSON
{
"event": "invitation.created",
"id": "event_01HWWSM92W0M1GE0DV8BZS00E5",
"data": {
"object": "invitation",
"id": "invitation_01HWWSMMQSP0FAN9PF071E77W9",
"email": "todd@example.com",
"state": "pending",
"accepted_at": null,
"revoked_at": null,
"expires_at": "2023-11-16T21:32:25.235Z",
"organization_id": "org_01HWWSSTF0QKDCXMZC911T8BTG",
"inviter_user_id": "user_01HYGAVW79Z32XVDXZJV0WM6Y9",
"created_at": "2023-11-16T21:32:25.235Z",
"updated_at": "2023-11-16T21:32:25.235Z"
},
"created_at": "2023-11-16T16:32:25.239Z"
}

Payload data corresponds to the Invitation object with the token omitted.

Triggered when a user is invited to sign up or to join an organization.

Magic Auth events

Events emitted when a user requests a Magic Auth code.

Magic Auth created event
JSON
{
"event": "magic_auth.created",
"id": "event_01HWWSTZVFADJG9M9EJMKXB043",
"data": {
"object": "magic_auth",
"id": "magic_auth_01HWWSVXCRMA5481VK9601SKQX",
"user_id": "user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E",
"email": "todd@example.com",
"expires_at": "2023-11-16T21:32:25.235Z",
"created_at": "2023-11-16T21:32:25.235Z",
"updated_at": "2023-11-16T21:32:25.235Z"
},
"created_at": "2023-11-16T16:32:25.239Z"
}

Payload data corresponds to the Magic Auth object with the code omitted.

Triggered when a user initiates Magic Auth and an authentication code is created.

Organization events

Events emitted when WorkOS organizations are created, updated, or deleted.

Organization created
JSON
{
"event": "organization.created",
"id": "event_04FKJ843CVE8F7BXQSPFH0M30K",
"data": {
"id": "org_01HV1VNQBQ24JVREYB94RFCNDC",
"name": "Foo Corp",
"object": "organization",
"domains": [
{
"id": "org_domain_01HV1VX5N18E48ETTHNNK54R6S",
"state": "verified",
"domain": "foo-corp.com",
"object": "organization_domain",
"organization_id": "org_01HV1VNQBQ24JVREYB94RFCNDC",
"verification_strategy": "manual"
}
],
"created_at": "2023-11-16T16:32:25.239Z",
"updated_at": "2023-11-16T16:32:25.239Z"
},
"created_at": "2023-11-16T16:32:25.239Z"
}

Payload data corresponds to the Organization object.

Triggered when an organization is created.

Organization updated
JSON
{
"event": "organization.updated",
"id": "event_04FKJ843CVE8F7BXQSPFH0M30K",
"data": {
"id": "org_01HV1VNQBQ24JVREYB94RFCNDC",
"name": "Foo Corp",
"object": "organization",
"domains": [
{
"id": "org_domain_01HV1VX5N18E48ETTHNNK54R6S",
"state": "verified",
"domain": "foo-corp.com",
"object": "organization_domain",
"organization_id": "org_01HV1VNQBQ24JVREYB94RFCNDC",
"verification_strategy": "manual"
}
],
"created_at": "2023-11-16T16:32:25.239Z",
"updated_at": "2023-11-16T17:32:25.239Z"
},
"created_at": "2023-11-16T17:32:25.239Z"
}

Payload data corresponds to the Organization object.

Triggered when an organization is updated.

Organization deleted
JSON
{
"event": "organization.deleted",
"id": "event_04FKJ843CVE8F7BXQSPFH0M30K",
"data": {
"id": "org_01HV1VNQBQ24JVREYB94RFCNDC",
"name": "Foo Corp",
"object": "organization",
"domains": [
{
"id": "org_domain_01HV1VX5N18E48ETTHNNK54R6S",
"state": "verified",
"domain": "foo-corp.com",
"object": "organization_domain",
"organization_id": "org_01HV1VNQBQ24JVREYB94RFCNDC",
"verification_strategy": "manual"
}
],
"created_at": "2023-11-16T16:32:25.239Z",
"updated_at": "2023-11-16T17:32:25.239Z"
},
"created_at": "2023-11-16T17:32:25.239Z"
}

Payload data corresponds to the Organization object.

Triggered when an organization is deleted

Organization domain events

Events emitted when verification status of an organization domain changes.

Organization domain verified event
JSON
{
"event": "organization_domain.verified",
"id": "event_07FKJ843CVE8F7BXQSPFH0M53A",
"data": {
"object": "organization_domain",
"id": "org_domain_01HACSKJ57W8M2Q0N2X759C5HS",
"organization_id": "org_01EHT88Z8J8795GZNQ4ZP1J81T",
"domain": "foo-corp.com",
"state": "verified",
"verification_token": "gBIJgYXZLjW8uHHpz614dkgqm",
"verification_strategy": "dns"
},
"created_at": "2021-06-25T19:07:33.155Z"
}

Payload data corresponds to the Organization Domain object.

Triggered when an organization domain is verified.

Organization domain verification failed event
JSON
{
"event": "organization_domain.verification_failed",
"id": "event_07FKJ843CVE8F7BXQSPFH0M53A",
"data": {
"reason": "domain_verification_period_expired",
"organization_domain": {
"object": "organization_domain",
"id": "org_domain_01HACSKJ57W8M2Q0N2X759C5HS",
"organization_id": "org_01EHT88Z8J8795GZNQ4ZP1J81T",
"domain": "foo-corp.com",
"state": "failed",
"verification_token": "gBIJgYXZLjW8uHHpz614dkgqm",
"verification_strategy": "dns"
}
},
"created_at": "2021-06-25T19:07:33.155Z"
}

Payload data contains a reason and an organization_domain which corresponds to the Organization Domain object.

Triggered when an organization domain verification fails.

Organization membership events

Events emitted when a User Management user joins or leaves an organization.

Organization membership created event
JSON
{
"event": "organization_membership.created",
"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"
}

Payload data corresponds to the Organization Membership object.

Triggered when an organization membership is created.

Organization membership deleted event
JSON
{
"event": "organization_membership.deleted",
"id": "event_04FKJ843CVE8F7BXQSPFH0M97T",
"data": {
"id": "om_01E4ZCR3C56J083X43JQXF3JK5",
"object": "organization_membership",
"user_id": "user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E",
"organization_id": "org_01E4ZCR3C56J083X43JQXF3JK5",
"status": "active",
"role": {
"slug": "member"
},
"created_at": "2023-11-16T21:32:25.235Z",
"updated_at": "2023-11-27T03:14:45.864Z"
},
"created_at": "2023-11-16T16:32:25.239Z"
}

Payload data corresponds to the Organization Membership object.

Triggered when an organization membership is deleted.

Organization membership updated event
JSON
{
"event": "organization_membership.updated",
"id": "event_04FKJ843CVE8F7BXQSPFH0M30K",
"data": {
"id": "om_01E4ZCR3C56J083X43JQXF3JK5",
"object": "organization_membership",
"user_id": "user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E",
"organization_id": "org_01E4ZCR3C56J083X43JQXF3JK5",
"status": "active",
"role": {
"slug": "member"
},
"created_at": "2023-11-16T21:32:25.235Z",
"updated_at": "2023-11-18T17:10:15.121Z"
},
"created_at": "2023-11-16T16:32:25.239Z"
}

Payload data corresponds to the Organization Membership object.

Triggered when an organization membership is updated.

Password reset events

Events emitted when a user requests to reset their password.

Password reset created event
JSON
{
"event": "password_reset.created",
"id": "event_01HYGAT2P3A8XJ4E5AR88J02ZV",
"data": {
"object": "password_reset",
"id": "password_reset_01HYGATMCSBX77HQHP29XT5WV6",
"user_id": "user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E",
"email": "todd@example.com",
"expires_at": "2023-11-16T21:32:25.235Z",
"created_at": "2023-11-16T21:32:25.235Z"
},
"created_at": "2023-11-16T16:32:25.239Z"
}

Payload data corresponds to the Organization Membership object with the token omitted.

Triggered when a user requests to reset their password.

Password reset succeeded event
JSON
{
"event": "password_reset.succeeded",
"id": "event_01HYGAT2P3A8XJ4E5AR88J02ZV",
"data": {
"object": "password_reset",
"id": "password_reset_01HYGATMCSBX77HQHP29XT5WV6",
"user_id": "user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E",
"email": "todd@example.com",
"expires_at": "2023-11-16T21:32:25.235Z",
"created_at": "2023-11-16T21:32:25.235Z"
},
"created_at": "2023-11-16T16:32:25.239Z"
}

Payload data corresponds to the Password Reset object with the token omitted.

Triggered when a user successfully resets their password.

Role events

Events emitted when roles are created or deleted in the WorkOS dashboard.

Role created event
JSON
{
"event": "role.created",
"id": "event_02F4KLW3C56P083X43JQXF4FO9",
"data": {
"object": "role",
"slug": "admin",
"permissions": ["posts:view"],
"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 a role is created.

Role deleted event
JSON
{
"event": "role.deleted",
"id": "event_01E4YCD3C56P083X43JQXF4JK5",
"data": {
"object": "role",
"slug": "developer",
"created_at": "2023-11-16T21:32:25.235Z",
"updated_at": "2023-11-18T10:12:18.121Z"
},
"created_at": "2023-11-21T18:14:01.399Z"
}

Triggered when a role is deleted.

Role updated event
JSON
{
"event": "role.updated",
"id": "event_01J21G0ED0N5Q5KZT9Z127Q2MZ",
"data": {
"object": "role",
"slug": "admin",
"permissions": ["posts:create", "posts:delete"],
"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 a role’s permissions are updated.

Session events

Events emitted when User Management sessions are created.

Session created event
JSON
{
"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 a session is created. Sessions started using impersonation will include an additional impersonator field with data about the impersonator.

User events

Events emitted when User Management users are created, updated, or deleted.

User created event
JSON
{
"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"
}

Payload data corresponds to the User object.

Triggered when a user is created.

User deleted event
JSON
{
"event": "user.deleted",
"id": "event_123456abcd",
"data": {
"object": "user",
"id": "user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E",
"email": "todd@example.com",
"first_name": "Todd",
"last_name": "Rundgren",
"email_verified": true,
"profile_picture_url": "https://workoscdn.com/images/v1/123abc",
"created_at": "2023-11-16T21:26:25.427Z",
"updated_at": "2023-11-17T04:00:03.937Z"
},
"created_at": "2023-11-18T04:18:13.126Z"
}

Payload data corresponds to the User object.

Triggered when a user is deleted.

User updated event
JSON
{
"event": "user.updated",
"id": "event_02F4KLW3C56P083X43JQXF4FO9",
"data": {
"object": "user",
"id": "user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E",
"email": "todd@example.com",
"first_name": "Todd",
"last_name": "Rundgren",
"email_verified": true,
"profile_picture_url": "https://workoscdn.com/images/v1/123abc",
"created_at": "2023-11-18T09:18:13.120Z",
"updated_at": "2023-11-19T11:05:10.539Z"
},
"created_at": "2023-11-19T11:05:10.550Z"
}

Payload data corresponds to the User object.

Triggered when a user is updated.

© WorkOS, Inc.
FeaturesUser ManagementSingle Sign-OnDirectory SyncAdmin PortalFine-Grained Authorization
DevelopersDocumentationChangelogOpen SourceAPI Status
ResourcesBlogPodcastPricingSecuritySupport
CompanyAboutCustomersCareersLegalPrivacy
© WorkOS, Inc.