Users & team
User role changed
user.role_changedFires when a company member is given a different role — either by a company administrator in the dashboard or by the partner that serves the company. The event is sent only when the role actually changes: re-assigning the same role produces no event (since 2026-09-29; before that the event was sent on every save, including no-op ones, and carried neither `previous_role` nor `source`). The `new_role` field is unchanged. The role may be a system one (`admin`, `manager`, `agent`) or a custom one (`custom:<ulid>`); `new_role_name` and `previous_role_name` carry the human-readable title. The event also reaches every member who was moved to another role when a custom role was deleted (`source: "role_deleted"`).
HTTP request
AISAR sends a signed POST request to your webhook_url:
POST {webhook_url}
Content-Type: application/json
X-AISAR-Signature: sha256=...
{
"event": "user.role_changed",
"event_id": "evt_01JXXXXXXXXXXXXXXXXXXXXX",
"timestamp": "2026-09-29T12:00:00.000000Z",
"company_id": 1,
"data": {
"user": {
"id": 55,
"name": "Aliya Seitova",
"email": "aliya@example.com",
"availability": "online"
},
"new_role": "admin",
"new_role_name": "Admin",
"previous_role": "agent",
"previous_role_name": "Agent",
"source": "company"
}
}The X-AISAR-Signature header carries an HMAC-SHA256 signature of the request body — use it to verify the request came from AISAR.
Example payload
{
"event": "user.role_changed",
"event_id": "evt_01JXXXXXXXXXXXXXXXXXXXXX",
"timestamp": "2026-09-29T12:00:00.000000Z",
"company_id": 1,
"data": {
"user": {
"id": 55,
"name": "Aliya Seitova",
"email": "aliya@example.com",
"availability": "online"
},
"new_role": "admin",
"new_role_name": "Admin",
"previous_role": "agent",
"previous_role_name": "Agent",
"source": "company"
}
}Payload fields
| Field | Type | Description |
|---|---|---|
user.id | integer | ID of the member whose role changed |
user.name | string | Full name (first + last combined) |
user.email | string | User email |
user.availability | string|null | Current availability status: `online`, `away`, `offline`, or `busy` |
new_role | string | The role now assigned to the member: `admin`, `manager`, `agent`, or a custom role key `custom:<ulid>` |
previous_role | string|null | The member's role before the change; `null` if they had none |
new_role_name | string | Title of the assigned role: `Admin`, `Manager`, `Agent` for system roles, or the given title of a custom role |
previous_role_name | string|null | Title of the previous role; `null` if there was none |
source | string | Who changed the role: `company` — a company administrator in the AISAR dashboard; `partner` — the partner that serves the company; `role_deleted` — an administrator deleted a custom role and the member was moved to the replacement |