Directory events

Explore webhook events related to directory operations in Scalekit, including user and group creation, updates, and deletions.

This page documents the webhook events Scalekit sends when an organization’s directory, its users or its groups change.

Event envelope
Directory connection events
Directory user events
Directory group events

Event envelope

Every directory event has the same top-level fields. The event-specific fields are in data. Keys can arrive in any order, so parse the body as JSON rather than matching it as text.

Field	Type	Description
`spec_version`	string	Webhook payload version. Currently `"1"`
`id`	string	Unique event ID, prefixed with `evt_`. Use it to ignore duplicate deliveries
`type`	string	Event type, such as `organization.directory.user_created`
`occurred_at`	string	When the event occurred, in RFC 3339 format
`environment_id`	string	Environment the event belongs to
`organization_id`	string	Organization the directory belongs to
`object`	string	`Directory`, `DirectoryUser` or `DirectoryGroup`
`data`	object	The directory, user or group. See each event below

Directory connection events

`organization.directory_created`

Sent when a directory is created for an organization. A SCIM or LDAP directory is enabled on creation, so organization.directory_enabled follows. A POLL directory is created disabled and sends only this event. data has four fields only.

{
  "spec_version": "1",
  "id": "evt_55136848686612000",
  "type": "organization.directory_created",
  "occurred_at": "2025-01-15T08:55:22.702860294Z",
  "environment_id": "env_27758032200925221",
  "organization_id": "org_55135410258444802",
  "object": "Directory",
  "data": {
    "directory_type": "SCIM",
    "id": "dir_55135622825771522",
    "organization_id": "org_55135410258444802",
    "provider": "OKTA"
  }
}

Field	Type	Description
`id`	string	Directory ID, prefixed with `dir_`
`organization_id`	string	Organization that owns the directory
`directory_type`	string	How the directory syncs, such as `SCIM`
`provider`	string	Directory provider, such as `OKTA`

`organization.directory_enabled`

Sent when directory sync is enabled for an organization.

1
{
2
  "spec_version": "1",
3
  "id": "evt_55136848686613000",
4
  "type": "organization.directory_enabled",
5
  "occurred_at": "2025-01-15T08:55:22.802860294Z",
6
  "environment_id": "env_27758032200925221",
7
  "organization_id": "org_55135410258444802",
8
  "object": "Directory",
9
  "data": {
10
    "directory_type": "SCIM",
11
    "enabled": true,
12
    "id": "dir_55135622825771522",
13
    "organization_id": "org_55135410258444802",
14
    "provider": "OKTA",
15
    "updated_at": "2025-01-15T08:55:22.792993454Z"
16
  }
17
}

Field	Type	Description
`id`	string	Directory ID, prefixed with `dir_`
`organization_id`	string	Organization that owns the directory
`directory_type`	string	How the directory syncs, such as `SCIM`
`provider`	string	Directory provider, such as `OKTA`
`enabled`	boolean	Always `true` on this event
`updated_at`	string	When the directory was last updated

`organization.directory_disabled`

Sent when directory sync is disabled for an organization. data has four fields only.

{
  "spec_version": "1",
  "id": "evt_53891640779079756",
  "type": "organization.directory_disabled",
  "occurred_at": "2025-01-06T18:45:21.057814Z",
  "environment_id": "env_53814739859406915",
  "organization_id": "org_53879494091473415",
  "object": "Directory",
  "data": {
    "directory_type": "SCIM",
    "id": "dir_53879621145330183",
    "organization_id": "org_53879494091473415",
    "provider": "OKTA"
  }
}

Field	Type	Description
`id`	string	Directory ID, prefixed with `dir_`
`organization_id`	string	Organization that owns the directory
`directory_type`	string	How the directory syncs, such as `SCIM`
`provider`	string	Directory provider, such as `OKTA`

`organization.directory_deleted`

Sent when a directory is deleted. Deleting a directory through the API or dashboard requires disabling it first. Deleting an organization also deletes its directories, enabled or not, and sends this event for each. data has four fields only.

{
  "spec_version": "1",
  "id": "evt_53891640779079900",
  "type": "organization.directory_deleted",
  "occurred_at": "2025-01-06T18:50:02.118243Z",
  "environment_id": "env_53814739859406915",
  "organization_id": "org_53879494091473415",
  "object": "Directory",
  "data": {
    "directory_type": "SCIM",
    "id": "dir_53879621145330183",
    "organization_id": "org_53879494091473415",
    "provider": "OKTA"
  }
}

Field	Type	Description
`id`	string	Directory ID, prefixed with `dir_`
`organization_id`	string	Organization that owns the directory
`directory_type`	string	How the directory syncs, such as `SCIM`
`provider`	string	Directory provider, such as `OKTA`

Directory user events

All three user events send the same user object in data.

organization.directory.user_created is sent when the directory provider creates an active user, or reactivates a deactivated user.
organization.directory.user_updated is sent when an active user’s attributes change, or when the user is added to or removed from a group.
organization.directory.user_deleted is sent when an active user is deactivated or deleted in the directory provider. data carries the last known user record. active is false when the user was deactivated.

Changes to a user who is already inactive send no event.

Directory user fields

The first seven fields are always sent. roles is computed by Scalekit and is sent on every user event when your environment has roles. The rest are sent only when the directory provider supplies them.

Field	Type	Description
`id`	string	Directory user ID, prefixed with `diruser_`
`organization_id`	string	Organization the user belongs to
`active`	boolean	Whether the user is active in the directory provider
`preferred_username`	string	The user’s `userName` from the provider. Empty string if not set
`dp_id`	string	The user’s `externalId` from the provider. Empty string if not set
`email`	string or null	Primary email address. `null` if the provider marks no email as primary
`groups`	array or null	Groups the user belongs to, each with `id` and `name`. `null` if the user is in no groups
`name`	string	Display name
`given_name`	string	Given (first) name
`family_name`	string	Family (last) name
`nickname`	string	Nickname
`picture`	string	Profile picture URL
`phone_number`	string	Work phone number
`address`	object	The user’s SCIM address of type `work`: `street_address`, `locality`, `state` (from SCIM `region`), `postal_code`, `country` and `formatted`
`profile`	string	Profile URL
`locale`	string	Locale
`zoneinfo`	string	Time zone
`language`	string	Preferred language
`title`	string	Job title
`user_type`	string	User type
`employee_id`	string	Employee number from the SCIM enterprise extension
`cost_center`	string	Cost center from the enterprise extension
`organization`	string	Organization from the enterprise extension
`division`	string	Division from the enterprise extension
`department`	string	Department from the enterprise extension
`manager`	object	The user’s manager, with `id`, `email` and `user_name`, when the manager is also in the directory
`roles`	array	Scalekit roles assigned through group-based role assignment, each with `role_name`. An empty array when no role applies
`dp_roles`	array or null	Roles as sent by the provider, each with `display`, `primary`, `type` and `value`. `null` if the provider sends an empty list
`entitlements`	array or null	Entitlements as sent by the provider, each with `display`, `primary`, `type` and `value`. `null` if the provider sends an empty list
`custom_attributes`	object	Custom attributes you mapped for this directory, plus `home_phone_number` and `mobile_phone_number` when the provider sends them
`raw_attributes`	object	The SCIM user resource as received from the provider

`organization.directory.user_created`

1
{
2
  "spec_version": "1",
3
  "id": "evt_53891546994442316",
4
  "type": "organization.directory.user_created",
5
  "occurred_at": "2025-01-06T18:44:25.153954Z",
6
  "environment_id": "env_53814739859406915",
7
  "organization_id": "org_53879494091473415",
8
  "object": "DirectoryUser",
9
  "data": {
10
    "active": true,
11
    "custom_attributes": {
12
      "mobile_phone_number": "+1-555-0101"
13
    },
14
    "department": "Engineering",
15
    "dp_id": "00u1a2b3c4d5e6f7g8h9",
16
    "email": "john.doe@acmecorp.com",
17
    "employee_id": "E1234",
18
    "family_name": "Doe",
19
    "given_name": "John",
20
    "groups": [
21
      {
22
        "id": "dirgroup_53891546960887900",
23
        "name": "Engineering"
24
      }
25
    ],
26
    "id": "diruser_53891546960887884",
27
    "locale": "en-US",
28
    "name": "John Doe",
29
    "organization_id": "org_53879494091473415",
30
    "phone_number": "+1-555-0100",
31
    "preferred_username": "john.doe@acmecorp.com",
32
    "raw_attributes": {
33
      "active": true,
34
      "externalId": "00u1a2b3c4d5e6f7g8h9",
35
      "userName": "john.doe@acmecorp.com"
36
    },
37
    "roles": [
38
      {
39
        "role_name": "billing_admin"
40
      }
41
    ],
42
    "title": "Software Engineer",
43
    "zoneinfo": "America/New_York"
44
  }
45
}

`organization.directory.user_updated`

1
{
2
  "spec_version": "1",
3
  "id": "evt_53891546994442317",
4
  "type": "organization.directory.user_updated",
5
  "occurred_at": "2025-01-06T18:44:25.153954Z",
6
  "environment_id": "env_53814739859406915",
7
  "organization_id": "org_53879494091473415",
8
  "object": "DirectoryUser",
9
  "data": {
10
    "active": true,
11
    "custom_attributes": {
12
      "mobile_phone_number": "+1-555-0101"
13
    },
14
    "department": "Engineering",
15
    "dp_id": "00u1a2b3c4d5e6f7g8h9",
16
    "email": "john.doe@acmecorp.com",
17
    "employee_id": "E1234",
18
    "family_name": "Doe",
19
    "given_name": "John",
20
    "groups": [
21
      {
22
        "id": "dirgroup_53891546960887900",
23
        "name": "Engineering"
24
      }
25
    ],
26
    "id": "diruser_53891546960887884",
27
    "locale": "en-US",
28
    "name": "John Doe",
29
    "organization_id": "org_53879494091473415",
30
    "phone_number": "+1-555-0100",
31
    "preferred_username": "john.doe@acmecorp.com",
32
    "raw_attributes": {
33
      "active": true,
34
      "externalId": "00u1a2b3c4d5e6f7g8h9",
35
      "userName": "john.doe@acmecorp.com"
36
    },
37
    "roles": [
38
      {
39
        "role_name": "billing_admin"
40
      }
41
    ],
42
    "title": "Senior Software Engineer",
43
    "zoneinfo": "America/New_York"
44
  }
45
}

`organization.directory.user_deleted`

This example is a deactivated user, so active is false.

1
{
2
  "spec_version": "1",
3
  "id": "evt_53891546994442318",
4
  "type": "organization.directory.user_deleted",
5
  "occurred_at": "2025-01-06T18:44:25.153954Z",
6
  "environment_id": "env_53814739859406915",
7
  "organization_id": "org_53879494091473415",
8
  "object": "DirectoryUser",
9
  "data": {
10
    "active": false,
11
    "custom_attributes": {
12
      "mobile_phone_number": "+1-555-0101"
13
    },
14
    "department": "Engineering",
15
    "dp_id": "00u1a2b3c4d5e6f7g8h9",
16
    "email": "john.doe@acmecorp.com",
17
    "employee_id": "E1234",
18
    "family_name": "Doe",
19
    "given_name": "John",
20
    "groups": [
21
      {
22
        "id": "dirgroup_53891546960887900",
23
        "name": "Engineering"
24
      }
25
    ],
26
    "id": "diruser_53891546960887884",
27
    "locale": "en-US",
28
    "name": "John Doe",
29
    "organization_id": "org_53879494091473415",
30
    "phone_number": "+1-555-0100",
31
    "preferred_username": "john.doe@acmecorp.com",
32
    "raw_attributes": {
33
      "active": false,
34
      "externalId": "00u1a2b3c4d5e6f7g8h9",
35
      "userName": "john.doe@acmecorp.com"
36
    },
37
    "roles": [
38
      {
39
        "role_name": "billing_admin"
40
      }
41
    ],
42
    "title": "Software Engineer",
43
    "zoneinfo": "America/New_York"
44
  }
45
}

Directory group events

All three group events send the same group object in data. Every key is sent, even when its value is null.

Field	Type	Description
`id`	string	Directory group ID, prefixed with `dirgroup_`
`organization_id`	string	Organization the group belongs to
`directory_id`	string	Directory the group belongs to
`display_name`	string	Group display name
`dp_id`	string or null	The group’s `externalId` from the provider. `null` if the provider doesn’t send one
`raw_attributes`	object or null	The SCIM group resource as received from the provider

`organization.directory.group_created`

1
{
2
  "spec_version": "1",
3
  "id": "evt_38862741515010639",
4
  "type": "organization.directory.group_created",
5
  "occurred_at": "2024-09-25T02:26:39.036398577Z",
6
  "environment_id": "env_32080745237316098",
7
  "organization_id": "org_38609339635728478",
8
  "object": "DirectoryGroup",
9
  "data": {
10
    "directory_id": "dir_38610496391217780",
11
    "display_name": "Engineering",
12
    "dp_id": "00g1a2b3c4d5e6f7g8h9",
13
    "id": "dirgroup_38862741498233423",
14
    "organization_id": "org_38609339635728478",
15
    "raw_attributes": {
16
      "displayName": "Engineering",
17
      "externalId": "00g1a2b3c4d5e6f7g8h9"
18
    }
19
  }
20
}

`organization.directory.group_updated`

1
{
2
  "spec_version": "1",
3
  "id": "evt_38864948910162368",
4
  "type": "organization.directory.group_updated",
5
  "occurred_at": "2024-09-25T02:48:34.745030921Z",
6
  "environment_id": "env_32080745237316098",
7
  "organization_id": "org_38609339635728478",
8
  "object": "DirectoryGroup",
9
  "data": {
10
    "directory_id": "dir_38610496391217780",
11
    "display_name": "Platform Engineering",
12
    "dp_id": "00g1a2b3c4d5e6f7g8h9",
13
    "id": "dirgroup_38862741498233423",
14
    "organization_id": "org_38609339635728478",
15
    "raw_attributes": {
16
      "displayName": "Platform Engineering",
17
      "externalId": "00g1a2b3c4d5e6f7g8h9"
18
    }
19
  }
20
}

`organization.directory.group_deleted`

1
{
2
  "spec_version": "1",
3
  "id": "evt_40650399597723966",
4
  "type": "organization.directory.group_deleted",
5
  "occurred_at": "2024-10-07T10:25:26.289331747Z",
6
  "environment_id": "env_12205603854221623",
7
  "organization_id": "org_39802449573184223",
8
  "object": "DirectoryGroup",
9
  "data": {
10
    "directory_id": "dir_39802485862301855",
11
    "display_name": "Admins",
12
    "dp_id": "7c66a173-79c6-4270-ac78-8f35a8121e0a",
13
    "id": "dirgroup_40072007005503806",
14
    "organization_id": "org_39802449573184223",
15
    "raw_attributes": {}
16
  }
17
}

Directory events

Table of contents

Event envelope

Directory connection events

organization.directory_created

organization.directory_enabled

organization.directory_disabled

organization.directory_deleted

Directory user events

Directory user fields

organization.directory.user_created

organization.directory.user_updated

organization.directory.user_deleted