role.created

project_id is always null for role events.

When this fires

Any member of the team (or a token carrying role:create) creates a new role. It also fires three times when a team is first seeded, once for each default role.

Required ability

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

Payload

{
  "id": "evt_01HX...",
  "type": "role.created",
  "created_at": "2026-05-18T10: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.created` 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, human-readable role code.
`data.name`	string	Display name.

Caveats

The full ability list is not embedded in this event; fetch the role from the API for complete detail.
The three default roles a new team is seeded with (admin, manager, viewer) emit this event too, one per role, at the moment the team is created.

role.updated — subsequent edits.
role.deleted — terminal state.
Role events overview — back to family overview.