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.
Previously, dsync.user.deleted and dsync.group.deleted webhook events were also sent for every user and group in the directory. These webhook events are redundant in this scenario, which is why they have been removed.
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.
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.
In addition to receiving events through webhooks, we recommend implementing the ability to reconcile directory state from our API. Decreased webhook reliability can occur in the event of a service outage or a slowdown in your app, or dependent cloud services. 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.
Most apps choose to receive WorkOS Directory Sync webhook events using a queue. The webhook events in this queue are reordered according to their timestamps and processed in that order. This method helps with receiving timely updates but requires the cron job method to reconcile any potential out of sync data.
For more information on webhooks, see our best practices guide.