role.updated
Role name or abilities change.
project_id is always null for role events.When this fires
A custom role's name, description, or ability set is edited.
Required ability
role:view-any — token must carry this at mint time to subscribe an endpoint to this event.
Payload
{
"id": "evt_01HX...",
"type": "role.updated",
"created_at": "2026-05-22T10:05:00Z",
"api_version": "2026-05-01",
"project_id": null,
"data": {
"team_id": "tem_01HX...",
"role": {
"id": "rol_01HX...",
"code": "plan-editor",
"name": "Plan Editor"
}
}
}Field reference
| Field | Type | Notes |
|---|---|---|
id | string ULID | Unique event id, prefixed evt_. Use for idempotent processing. |
type | string | Always role.updated for this event. |
created_at | ISO 8601 timestamp | Server-side emission time. |
api_version | string | Webhook API contract version. |
project_id | null | Always null — account-level event. |
data.team_id | string ULID | Team the role belongs to. |
data.role.id | string ULID | Role identifier. |
data.role.code | string | Stable role code (immutable across renames). |
data.role.name | string | Updated display name. |
Caveats
- This event fires on both name changes and ability-set changes; fetch the role from the API to determine what actually changed.
- Collaborators currently holding the role pick up the new abilities immediately on next request.
Related events
role.created— predecessor.team.member.role_changed— fires when a collaborator's role assignment changes (different surface).- Role events overview — back to family overview.
How is this guide?