role.updated

project_id is always null for role events.

When this fires

A role's name, description, or permission set is saved — including the default admin, manager and viewer roles. The event is emitted on every save, even one that changes nothing, so treat it as "the role was written" rather than "the role changed".

Required ability

role:view — 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": "a83f0d51-4c92-4b7e-8615-2fd9e70a3c86",
    "role_id": "d05e1a83-7c46-4f29-b613-8ae407c9d251",
    "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 UUID	Team the role belongs to.
`data.role_id`	string UUID	Role identifier.
`data.code`	string	Stable role code (immutable across renames).
`data.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.

role.created — predecessor.
team.member.role_changed — fires when a collaborator's role assignment changes (different surface).
Role events overview — back to family overview.