Learn how to handle events that occur in Directory Sync.
Directory Sync events represent actions performed within directory providers. 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 form the basis of user lifecycle management (ULM).
WorkOS provides information about these actions through a set of structured events. Your app interfaces with WorkOS to receive these events via webhooks. This reference guide will cover the events Directory Sync produces, what they mean, and how to handle them in your app.
This event occurs when you or your customer have successfully created a connection between WorkOS and your customer’s directory provider.
dsync.activated is triggered if you manually create the directory connection in the Developer Dashboard, or your customer sets the connection up using the Admin Portal.
The directory ID identifies a connection with the directory of a particular customer. Your app should save it and associate the directory ID with the corresponding organization ID.
This event occurs when a Directory Sync connection is deleted in WorkOS, thus tearing down the link between your customer’s directory provider and your app.
A connection can be deleted through the Admin Portal, Developer Dashboard, or WorkOS API. At this point your app should remove the association between the corresponding organization and its directory, as it no longer exists. Directories, users, and groups are typically deleted if your app offboards a customer altogether.
When receiving a dsync.deleted event, you can ignore the connection’s state attribute, since it indicates the state before the deletion occurs. When a directory is deleted in WorkOS, a sole dsync.deleted webhook event is sent.
When a dsync.deleted webhook event is received, it indicates that the users and groups in that directory have been deleted in WorkOS. You can process the dsync.deleted webhook event accordingly in your application, removing the organization’s groups and its users from your application or marking them as deleted. dsync.user.deleted and dsync.group.deleted webhook events will not be sent for the deleted directory.
This event occurs when an IT admin creates a user using their directory provider. It is standard to create and provision the user in your app when you receive this event.
You can add this user to your users table in your app and associate them with the directory ID and organization ID. You can begin to engage with the user at this point, e.g., send the user a “Getting Started” email.
When creating a directory, you receive dsync.user.created webhooks for each user in that directory.
This event occurs when users’ attributes change. These attributes may be standard attributes, auto-mapped attributes, or custom-mapped attributes.
The payload for dsync.user.updated webhooks shows changes between directory group snapshots in the previous_attributes property.
This event occurs when a user is hard-deleted from a directory. Typically, you would remove the user from your app in this case.
When users are removed from a directory, most providers will use a form of soft user deletion. In these cases, rather than recieving a dsync.user.deleted event, you will recieve a dsync.user.updated event with the user's state marked as inactive.
This event occurs when creating a directory group in the directory provider. WorkOS also sends this event when a directory connection is established.
When WorkOS ingests this event, it first processes the users in the group. So, in most cases, you would receive dsync.user.created, then dsync.group.created, and finally, dsync.group.user_added.
For more information on best practices for out-of-order events, please see this guide.
This event is sent when an attribute of a directory group has changed.
The payload for this event’s webhook shows changes between directory group snapshots in the previous_attributes property.
This event occurs when deleting a directory group in the directory provider.
When a dsync.group.deleted webhook event is received, it indicates that the members in that group have been deleted in WorkOS. You can process the dsync.group.deleted webhook event accordingly in your application, removing the group's members from your application or marking them as deleted. dsync.group.user_removed webhook events will not be sent for the members in the deleted group.
If your app relies on groups to sync users or map roles, you should remove access for the users who belonged to the deleted group.
This event occurs when adding a directory user to a directory group.
If you map roles using groups, you should assign the group’s role to the newly added user.
This event occurs when removing a directory user from a directory group.
If you map roles using groups, you should remove the group’s role from the user who belonged to the group.
The WorkOS API allows for data reconciliation for your app. You can use the WorkOS API to pull the latest data to reconcile any data discrepancies between WorkOS and your app.
A standard method apps use for data reconciliation is to set up a cron job that pulls from the WorkOS API on a consistent interval, e.g., every 1 to 6 hours, depending on your app’s user provisioning volume.
Known issue: Keeping track of WorkOS updated timestamps is of limited use right now because group membership changes for users do not alter the WorkOS updated_at timestamp. We're actively working on this issue.
The general approach for performing a full sync of Directory Sync objects goes as follows:
For more information on Events API data reconciliation, see our best practices guide.
For more information on Webhooks data reconciliation, see our best practices guide.