# Directory events

Directory changes are committed with an outbox event. A rolled-back change leaves no event. Events carry the directory and organization context and a per-directory sequence number.

| Event                                         | Consumer action                                                 |
| --------------------------------------------- | --------------------------------------------------------------- |
| `dsync.user.created`                          | Create or link an allowed local identity                        |
| `dsync.user.updated`                          | Update allowed attributes; revoke access when state is inactive |
| `dsync.user.deleted`                          | Disable the linked identity and revoke application sessions     |
| `dsync.group.created`, `updated`, `deleted`   | Maintain the directory's local groups                           |
| `dsync.group.user_added`, `user_removed`      | Update membership and derived permissions                       |
| `dsync.first_request`, `activated`, `deleted` | Update setup state or reconcile a removed directory             |

User payloads include the directory user's ID, directory ID, organization ID and state. Membership payloads identify the group and user. Validate each event's data for its type; the generic event envelope does not constrain every nested business field.

On a user leaving the verified domains, membership-removal events precede `dsync.user.deleted` with `reason=out_of_domain`. A user coming back emits created, then membership additions. A group's members leave before its deletion event.

Verify [webhook signatures](/events/webhook-verification/) before parsing or applying data. Deduplicate by event ID, persist effects and ordering progress together, and use [ordering recovery](/directory-sync/ordering/) after gaps.
