> For AI agents: [llms.txt](https://docs.trustedauth.com/llms.txt) provides a Markdown index of this documentation.

# User events

User events notify you when user accounts are created, updated, deleted, or when users complete registration. When a user event is triggered, IDaaS sends an HTTP POST request to your configured webhook URL with a JSON payload containing the event details.

## Payload structure

Every user event payload has this structure:

```json
{
  "id": "770fa622-94bd-43f6-c938-668877662222",
  "type": "user.created",
  "accountId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "eventTime": "2024-03-15T10:00:00.000Z",
  "data": {
    // Event-specific data here
  }
}
```

The `data` object contains event-specific fields. See the event examples later on this page for the full `data` object for each event type.

### Top-level fields

| Field       | Type   | Description                                        |
| ----------- | ------ | -------------------------------------------------- |
| `id`        | string | Unique identifier for this webhook delivery        |
| `type`      | string | The event that occurred (e.g., `user.created`)     |
| `accountId` | string | Your account identifier                            |
| `eventTime` | string | When the event occurred (ISO 8601 format)          |
| `data`      | object | Details about what happened (varies by event type) |

## Event types

### user.created

Triggered when an administrator creates a new user account.

**Example payload:**

```json
{
  "id": "770fa622-94bd-43f6-c938-668877662222",
  "type": "user.created",
  "accountId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "eventTime": "2024-03-15T10:00:00.000Z",
  "data": {
    "subject": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "subjectName": "adminuser",
    "subjectType": "USER",
    "resourceName": "Administration Portal",
    "sourceIp": "192.168.1.50",
    "subscriberAdminRoleName": "System Administrator",
    "entityType": "USERS",
    "entityId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "entityName": "janesmith",
    "entityAttributes": {
      "userId": "janesmith",
      "firstName": "Jane",
      "lastName": "Smith",
      "email": "janesmith@example.com"
    }
  }
}
```

The `data` object includes the following fields:

| Field                     | Description                                                    |
| ------------------------- | -------------------------------------------------------------- |
| `subject`                 | ID of the admin who created the user                           |
| `subjectName`             | Username of the admin who created the user                     |
| `subjectType`             | Always `USER` for admin actions                                |
| `resourceName`            | Where the action was performed (e.g., "Administration Portal") |
| `sourceIp`                | IP address of the admin                                        |
| `subscriberAdminRoleName` | The admin's role (e.g., "System Administrator")                |
| `entityType`              | Always `USERS` for user events                                 |
| `entityId`                | ID of the newly created user                                   |
| `entityName`              | Username of the newly created user                             |
| `entityAttributes`        | Details about the new user (see below)                         |

The `entityAttributes` object always includes these fields:

- `userId` - The username
- `firstName` - First name
- `lastName` - Last name
- `email` - Email address

### user.updated

Triggered when an administrator modifies a user account.

**Example payload:**

```json
{
  "id": "aa0ad955-a7ea-96a9-f26b-99bb00995555",
  "type": "user.updated",
  "accountId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "eventTime": "2024-03-15T11:20:00.000Z",
  "data": {
    "subject": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "subjectName": "adminuser",
    "subjectType": "USER",
    "resourceName": "Administration Portal",
    "sourceIp": "192.168.1.50",
    "subscriberAdminRoleName": "System Administrator",
    "entityType": "USERS",
    "entityId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "entityName": "janesmith",
    "entityAttributes": {
      "mobile": "+1-555-123-4567",
      "lastName": "Smith-Johnson",
      "groups": ["Engineering", "Security Team"],
      "customUserAliases": ["jsmith"]
    }
  }
}
```

This event uses the same `data` structure as `user.created`, but `entityAttributes` contains only the fields that changed.

In the example above, only these fields were updated:

- `mobile` - Phone number was added or changed
- `lastName` - Last name was changed
- `groups` - Group membership was updated
- `customUserAliases` - Aliases were added or changed

Any user field can appear here if it was modified.

### user.deleted

Triggered when an administrator deletes a user account.

**Example payload:**

```json
{
  "id": "880ab733-a5ce-74a7-d049-779988773333",
  "type": "user.deleted",
  "accountId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "eventTime": "2024-03-15T16:45:00.000Z",
  "data": {
    "subject": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "subjectName": "adminuser",
    "subjectType": "USER",
    "resourceName": "Administration Portal",
    "sourceIp": "192.168.1.50",
    "subscriberAdminRoleName": "System Administrator",
    "entityType": "USERS",
    "entityId": "c3d4e5f6-a7b8-9012-cdef-345678901234",
    "entityName": "olduser"
  }
}
```

This event uses the same `data` structure as other user events, but does not include the `entityAttributes` field.

All information about the deleted user is in:

- `entityId` - ID of the deleted user
- `entityName` - Username of the deleted user

### user.registration.completed

Triggered when a user completes their account registration.

**Example payload:**

```json
{
  "id": "990ac844-a6df-85a8-e15a-88aa99884444",
  "type": "user.registration.completed",
  "accountId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "eventTime": "2024-03-15T09:30:00.000Z",
  "data": {
    "subject": "d4e5f6a7-b8c9-0123-abcd-456789012345",
    "subjectName": "newuser",
    "subjectType": "USER",
    "resourceName": "User Portal",
    "sourceIp": "203.0.113.42",
    "entityType": "USERS",
    "entityId": "d4e5f6a7-b8c9-0123-abcd-456789012345",
    "entityName": "newuser",
    "entityAttributes": {
      "registrationRequired": false
    }
  }
}
```

The `data` object includes the following fields:

| Field              | Description                                            |
| ------------------ | ------------------------------------------------------ |
| `subject`          | ID of the user who completed registration              |
| `subjectName`      | Username of the user who completed registration        |
| `subjectType`      | Always `USER`                                          |
| `resourceName`     | Where registration was completed (e.g., "User Portal") |
| `sourceIp`         | IP address of the user                                 |
| `entityType`       | Always `USERS`                                         |
| `entityId`         | ID of the user (same as `subject`)                     |
| `entityName`       | Username (same as `subjectName`)                       |
| `entityAttributes` | Contains `registrationRequired: false`                 |

Key differences from other events:

- **No `subscriberAdminRoleName`** - This is a user-initiated action, not an admin action
- **`subject` is the user themselves** - In other events, `subject` is the admin who performed the action