# Events Events represent activity that has occurred within WorkOS or within third-party identity and directory providers. Your app can [sync the data](https://workos.com/docs/events/data-syncing) via either the events API or webhooks. #### Event object All event objects share a similar structure. | Attribute | Description | | ------------ | -------------------------------------------------------------------------- | | `event` | A string that distinguishes the event type. | | `id` | Unique identifier for the event. | | `data` | Event payload. Payloads match the corresponding [API objects](https://workos.com/docs/reference). | | `created_at` | Timestamp of when the event occurred. | | `context` | An optional object of extra information relevant to the event. | ## Agent registration events Events emitted during the agent registration lifecycle, including creation, claim attempts, claim completion, credential issuance, and organization switching. #### Agent registration claim attempt created event Triggered when a claim attempt is initiated for an agent registration. #### Agent registration claim completed event Triggered when an agent registration claim is successfully completed. #### Agent registration created event Triggered when a new agent registration is created. #### Agent registration credential issued event Triggered when a credential is issued for an agent registration. #### Agent registration organization switched event Triggered when an agent registration is moved to a different organization. ## API key events Events emitted when [API keys](https://workos.com/docs/authkit/api-keys) are created, updated, or revoked. #### API key created event Triggered when an API key is created. #### API key revoked event Triggered when an API key is revoked. #### API key updated event Triggered when an API key expiration is set, changed, or cleared. ## Authentication events Each step in the [authentication](https://workos.com/docs/reference/authkit/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 Triggered when a user fails to verify their email. #### Email verification succeeded event Triggered when a user successfully verifies their email. #### Magic Auth failed event Triggered when a user fails to authenticate via Magic Auth. #### Magic Auth succeeded event Triggered when a user successfully authenticates via Magic Auth. #### MFA failed event Triggered when a user fails to authenticate with a multi-factor authentication code. #### MFA succeeded event Triggered when a user successfully authenticates with a multi-factor authentication code. #### OAuth failed event Triggered when a user fails to authenticate via OAuth. #### OAuth succeeded event Triggered when a user successfully authenticates via OAuth. #### Password authentication failed event Triggered when a user fails to authenticate with password credentials. #### Password authentication succeeded event Triggered when a user successfully authenticates with password credentials. #### Passkey authentication failed event Triggered when a user fails to authenticate with a passkey. #### Passkey authentication succeeded event Triggered when a user successfully authenticates with a passkey. #### SSO failed event Triggered when a user fails to authenticate with Single Sign-On. #### SSO succeeded event Triggered when a user successfully authenticates with Single Sign-On. #### Radar risk detected event 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. Also emitted when a SAML certificate is renewed for the connection. #### Connection activated event Payload `data` corresponds to the [Connection](https://workos.com/docs/reference/sso/connection) object. Triggered when a connection is activated. #### Connection deactivated event Payload `data` corresponds to the [Connection](https://workos.com/docs/reference/sso/connection) object. Triggered when a connection is deactivated. #### Connection deleted event Payload `data` corresponds to the [Connection](https://workos.com/docs/reference/sso/connection) object. Triggered when a connection is deleted. The `state` attribute indicates connection state before deletion. #### Connection certificate renewed event The `certificate_type` can be one of `ResponseSigning`, `RequestSigning`, or `ResponseEncryption`. Triggered when a SAML certificate is renewed either in the Dashboard or Admin Portal. #### Connection certificate renewal required event The `certificate_type` can be one of `ResponseSigning`, `RequestSigning`, or `ResponseEncryption`. Triggered when a SAML certificate is expiring (multiple events are sent out as it approaches expiry), or expired (once every 7 days after expiry). ## 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](https://workos.com/docs/directory-sync/understanding-events). #### Directory activated event Payload `data` is based on the [Directory](https://workos.com/docs/reference/directory-sync/directory) object, but the `domain` property is replaced with a `domains` array of [Organization Domain](reference/organization-domain). Triggered when a [directory is activated](https://workos.com/docs/directory-sync/understanding-events/directory-events/dsync-activated). #### Directory deleted event Payload `data` is based on the [Directory](https://workos.com/docs/reference/directory-sync/directory) object, except the `domain` property is omitted. Triggered when a [directory is deleted](https://workos.com/docs/directory-sync/understanding-events/directory-events/dsync-deleted). The `state` attribute indicates directory state before deletion. #### Directory group created event Payload `data` corresponds to the [Directory Group](https://workos.com/docs/reference/directory-sync/directory-group) object. Triggered when a [directory group is created](https://workos.com/docs/directory-sync/understanding-events/directory-group-events/dsync-group-created). #### Directory group deleted event Payload `data` corresponds to the [Directory Group](https://workos.com/docs/reference/directory-sync/directory-group) object. Triggered when a [directory group is deleted](https://workos.com/docs/directory-sync/understanding-events/directory-group-events/dsync-group-deleted). #### Directory group updated event Payload `data` corresponds to the [Directory Group](https://workos.com/docs/reference/directory-sync/directory-group) object. Triggered when a [directory group is updated](https://workos.com/docs/directory-sync/understanding-events/directory-group-events/dsync-group-updated). #### Directory group user added event Payload `data` contains a `user` which corresponds to the [Directory User](https://workos.com/docs/reference/directory-sync/directory-user) object and a `group` which corresponds to the [Directory Group](https://workos.com/docs/reference/directory-sync/directory-group) object. The `groups` field is omitted from the `user` object to avoid performance issues in large directories. Triggered when a [directory group user is added](https://workos.com/docs/directory-sync/understanding-events/directory-group-events/dsync-group-user-added). #### Directory group user removed event Payload `data` contains a `user` which corresponds to the [Directory User](https://workos.com/docs/reference/directory-sync/directory-user) object and a `group` which corresponds to the [Directory Group](https://workos.com/docs/reference/directory-sync/directory-group) object. The `groups` field is omitted from the `user` object to avoid performance issues in large directories. Triggered when a [directory group user is removed](https://workos.com/docs/directory-sync/understanding-events/directory-group-events/dsync-group-user-removed). #### Directory user created event Payload `data` corresponds to the [Directory User](https://workos.com/docs/reference/directory-sync/directory-user) object. The `groups` field is omitted to avoid performance issues in large directories. Triggered when a [directory user is created](https://workos.com/docs/directory-sync/understanding-events/directory-user-events/dsync-user-created). #### Directory user deleted event Payload `data` corresponds to the [Directory User](https://workos.com/docs/reference/directory-sync/directory-user) object. The `groups` field is omitted to avoid performance issues in large directories. Triggered when a [directory user is deleted](https://workos.com/docs/directory-sync/understanding-events/directory-user-events/dsync-user-deleted). The `state` attribute indicates directory user state at time of deletion. #### Directory user updated event Payload `data` corresponds to the [Directory User](https://workos.com/docs/reference/directory-sync/directory-user) object. The `groups` field is omitted to avoid performance issues in large directories. Triggered when a [directory user is updated](https://workos.com/docs/directory-sync/understanding-events/directory-user-events/dsync-user-updated). ## Email verification events Events emitted when a user is required to verify their email. #### Email verification created event Payload `data` corresponds to the [Email verification](https://workos.com/docs/authkit/email-verification) object with the `code` omitted. Triggered when a user is required to verify their email and a code is created. ## Feature flag events Events emitted when WorkOS feature flags are created, updated, deleted, or their rules are updated. #### Feature flag created event Payload `data` corresponds to the [Feature Flag](https://workos.com/docs/reference/feature-flags) object. Triggered when a feature flag is created. #### Feature flag updated event Payload `data` corresponds to the [Feature Flag](https://workos.com/docs/reference/feature-flags) object. Triggered when a feature flag is updated. #### Feature flag deleted event Payload `data` corresponds to the [Feature Flag](https://workos.com/docs/reference/feature-flags) object. Triggered when a feature flag is deleted. #### Feature flag rule updated event Payload `data` corresponds to the [Feature Flag](https://workos.com/docs/reference/feature-flags) object. Triggered when a feature flag's rules are modified. ## Group events Events emitted when [groups](https://workos.com/docs/authkit/groups) are created, updated, deleted, or their members change. #### Group created event Payload `data` corresponds to the [Group](https://workos.com/docs/reference/groups) object. Triggered when a group is created. #### Group updated event Payload `data` corresponds to the [Group](https://workos.com/docs/reference/groups) object. Triggered when a group is updated. #### Group deleted event Payload `data` corresponds to the [Group](https://workos.com/docs/reference/groups) object. Triggered when a group is deleted. #### Group member added event Payload `data` contains the `group_id` and `organization_membership_id` of the added member. Triggered when an organization membership is added to a group. #### Group member removed event Payload `data` contains the `group_id` and `organization_membership_id` of the removed member. Triggered when an organization membership is removed from a group. ## Invitation events Events emitted when an [AuthKit user](https://workos.com/docs/reference/authkit/user) is invited to join an organization. #### Invitation accepted event Payload `data` corresponds to the [Invitation](https://workos.com/docs/reference/authkit/invitation) object with the `token` and `accept_invitation_url` omitted. Triggered when a user accepts an invitation. #### Invitation created event Payload `data` corresponds to the [Invitation](https://workos.com/docs/reference/authkit/invitation) object with the `token` and `accept_invitation_url` omitted. Triggered when a user is invited to sign up or to join an organization. #### Invitation resent event Payload `data` corresponds to the [Invitation](https://workos.com/docs/reference/authkit/invitation) object with the `token` and `accept_invitation_url` omitted. Triggered when an invitation is resent. #### Invitation revoked event Payload `data` corresponds to the [Invitation](https://workos.com/docs/reference/authkit/invitation) object with the `token` and `accept_invitation_url` omitted. Triggered when an invitation is revoked. ## Magic Auth events Events emitted when a user requests a Magic Auth code. #### Magic Auth created event Payload `data` corresponds to the [Magic Auth](https://workos.com/docs/reference/authkit/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 Payload `data` corresponds to the [Organization](https://workos.com/docs/reference/organization) object. Triggered when an organization is created. #### Organization updated Payload `data` corresponds to the [Organization](https://workos.com/docs/reference/organization) object. Triggered when an organization is updated. #### Organization deleted Payload `data` corresponds to the [Organization](https://workos.com/docs/reference/organization) object. Triggered when an organization is deleted ## Organization domain events Events emitted when organization domains are created, updated, deleted, or their verification status changes. #### Organization domain created event Payload `data` corresponds to the [Organization Domain](https://workos.com/docs/reference/domain-verification) object. Triggered when an organization domain is created. #### Organization domain updated event Payload `data` corresponds to the [Organization Domain](https://workos.com/docs/reference/domain-verification) object. Triggered when an organization domain is updated. #### Organization domain deleted event Payload `data` corresponds to the [Organization Domain](https://workos.com/docs/reference/domain-verification) object. Triggered when an organization domain is deleted. #### Organization domain verified event Payload `data` corresponds to the [Organization Domain](https://workos.com/docs/reference/domain-verification) object. Triggered when an organization domain is verified. #### Organization domain verification failed event Payload `data` contains a `reason` and an `organization_domain` which corresponds to the [Organization Domain](https://workos.com/docs/reference/domain-verification) object. Triggered when an organization domain verification fails. ## Organization membership events Events emitted when an [AuthKit user](https://workos.com/docs/reference/authkit/user) joins or leaves an organization. #### Organization membership created event Payload `data` corresponds to the [Organization Membership](https://workos.com/docs/reference/authkit/organization-membership) object. Triggered when an organization membership is created. #### Organization membership deleted event Payload `data` corresponds to the [Organization Membership](https://workos.com/docs/reference/authkit/organization-membership) object. Triggered when an organization membership is deleted. #### Organization membership updated event Payload `data` corresponds to the [Organization Membership](https://workos.com/docs/reference/authkit/organization-membership) object. Triggered when an organization membership is updated. ## Custom role events Events emitted when [custom roles](https://workos.com/docs/reference/roles/custom-role) are created, updated, or deleted. #### Custom role created event Payload `data` corresponds to the custom role object. Triggered when a custom role is created. #### Custom role deleted event Payload `data` corresponds to the custom role object. Triggered when a custom role is deleted. #### Custom role updated event Payload `data` corresponds to the custom role object. Triggered when a custom role is updated. ## Password reset events Events emitted when a user requests to reset their password. #### Password reset created event Payload `data` corresponds to the [Organization Membership](https://workos.com/docs/reference/authkit/password-reset) object with the `token` omitted. Triggered when a user requests to reset their password. #### Password reset succeeded event Payload `data` corresponds to the [Password Reset](https://workos.com/docs/reference/authkit/password-reset) object with the `token` omitted. Triggered when a user successfully resets their password. ## Permission events Events emitted when [permissions](https://workos.com/docs/reference/roles/permission) are created, updated, or deleted. #### Permission created event Payload `data` corresponds to the permission object. Triggered when a permission is created. #### Permission deleted event Payload `data` corresponds to the permission object. Triggered when a permission is deleted. #### Permission updated event Payload `data` corresponds to the permission object. Triggered when a permission is updated. ## Pipes events Events emitted when a [Pipes](https://workos.com/docs/pipes) connected account is connected, disconnected, or requires reauthorization. #### Pipes connected account connected event Triggered when a connected account completes authorization. #### Pipes connected account disconnected event Triggered when a connected account is disconnected. #### Pipes connected account reauthorization needed event Triggered when a connected account needs to be reauthorized. ## Radar events Events emitted when [Radar](https://workos.com/docs/authkit/radar) creates a challenge during authentication. #### Radar challenge created event Triggered when Radar creates a challenge during authentication. The `type` field indicates the challenge type (e.g. `email`). Use the `radar_challenge_id` to fetch the full challenge details via `GET /user_management/radar_challenges/:id`. ## Role events Events emitted when [environment roles](https://workos.com/docs/reference/roles/role) are created, updated, or deleted. #### Role created event Triggered when a role is created. #### Role deleted event Triggered when a role is deleted. #### Role updated event Triggered when a role's permissions are updated. ## Session events Events emitted when AuthKit sessions are created. #### Session created event Triggered when a session is created. Sessions started using [impersonation](https://workos.com/docs/authkit/impersonation) will include an additional `impersonator` field with data about the impersonator. #### Session revoked event Triggered when an issued session is revoked for a user. ## User events Events emitted when [AuthKit users](https://workos.com/docs/reference/authkit/user) are created, updated, or deleted. #### User created event Payload `data` corresponds to the [User](https://workos.com/docs/reference/authkit/user) object. Triggered when a user is created. #### User deleted event Payload `data` corresponds to the [User](https://workos.com/docs/reference/authkit/user) object. Triggered when a user is deleted. #### User updated event Payload `data` corresponds to the [User](https://workos.com/docs/reference/authkit/user) object. Triggered when a user is updated. ## Vault events Events emitted when [Vault](https://workos.com/docs/vault) data, keys, or metadata are accessed or modified. #### Vault BYOK key deleted event Triggered when a bring-your-own-key (BYOK) configuration is deleted from an organization. #### Vault BYOK key verification completed event Triggered when bring-your-own-key (BYOK) verification completes for an organization. #### Vault data created event Triggered when a new encrypted object is stored in Vault. #### Vault data deleted event Triggered when an encrypted object is deleted from Vault. #### Vault data read event Triggered when an encrypted object is read from Vault. #### Vault data updated event Triggered when an existing encrypted object is updated in Vault. #### Vault DEK decrypted event Triggered when a data encryption key (DEK) is decrypted. #### Vault DEK read event Triggered when one or more data encryption keys (DEKs) are read. #### Vault KEK created event Triggered when a new key encryption key (KEK) is created. #### Vault metadata read event Triggered when metadata for a Vault store is read. #### Vault names listed event Triggered when the list of Vault store names is retrieved.