role.deleted

project_id is always null for role events.

When this fires

A role that no collaborator currently holds is deleted. A role still assigned to someone cannot be deleted at all — the database refuses it.

Required ability

role:view — token must carry this at mint time to subscribe an endpoint to this event.

Payload

{
  "id": "evt_01HX...",
  "type": "role.deleted",
  "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"
  }
}

Field reference

Field	Type	Notes
`id`	string ULID	Unique event id, prefixed `evt_`. Use for idempotent processing.
`type`	string	Always `role.deleted` 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 belonged to.
`data.role_id`	string UUID	Role that was deleted.
`data.code`	string	Last-known stable role code.

Caveats

Deleting is restricted to the role's creator, unless the caller owns the team — a team owner can delete any role in their team, including the default admin, manager and viewer roles. The dashboard hides the action for roles you did not create; the API and MCP surfaces do not.

role.created — first event in the lifecycle.
team.member.role_changed — emits for explicit role re-assignments.
Role events overview — back to family overview.