AUTH4D-362 user.banned, user.ban_updated and user.unbanned webhook events

This fragment extends AUTH4D-158 (repository file docs/api-spec/auth4d-158.md), AUTH4D-216 (repository file docs/api-spec/auth4d-216.md) and AUTH4D-310 (repository file docs/api-spec/auth4d-310.md). It adds three Flows event types, user.banned, user.ban_updated and user.unbanned, which webhook endpoints can subscribe to. No endpoint, signature header or migration changes: webhook_endpoints.event_types is a JSON array and fan-out matches types generically.

Events

FlowEventTypeSchema and FlowEventSchema in packages/contracts accept the three types. The envelope is the same as for every other event. data is strict:

Type data
user.banned { "ban_id": "ban_…", "expires_at": … }
user.ban_updated { "ban_id": "ban_…", "expires_at": … }
user.unbanned { "ban_id": "ban_…" }

expires_at is an ISO 8601 date-time when the ban ends, or null for a permanent ban. For user.ban_updated it is the end after the change. The ban’s reason is a note for the project’s team and is never published, the same rule as for the management.user.banned, management.user.ban_updated and management.user.ban_revoked audit events.

{
  "event_id": "evt_r4Tn8Wq2Lc6Yh0Pz3Kd9Jb5Vs1Mf7Xg2Ae8Uo4Ni6Hk",
  "version": 1,
  "type": "user.banned",
  "tenant_id": "ten_0123456789abcdef",
  "application_id": null,
  "user_id": "usr_0123456789abcdef",
  "occurred_at": "2026-10-25T14:02:51.330Z",
  "context": {},
  "data": { "ban_id": "ban_0123456789abcdef0123", "expires_at": "2026-10-26T14:02:51.330Z" }
}

When it is published

  • POST /management/tenants/{tenantId}/users/{userId}/bans publishes user.banned once the ban row is written, the player’s sessions are revoked and the audit event is appended. When sessions were revoked, the existing session.revoked (reason: "admin") is still published as well.
  • PATCH /management/tenants/{tenantId}/users/{userId}/bans/{banId} publishes user.ban_updated after an active ban is changed, including a change to the reason only.
  • POST /management/tenants/{tenantId}/users/{userId}/bans/{banId}/revoke publishes user.unbanned only when this request lifted the ban (revoked: true). Revoking a ban that was already revoked answers revoked: false and publishes nothing.
  • Nothing is published for a refused request: an invalid body (400), ban_active or too_many_bans (409), ban_inactive (409) for a change to a revoked or expired ban, or an unknown player or ban (404).
  • A timed ban that runs out on its own publishes user.unbanned from the lifecycle cron, up to about 10 minutes late, under the action key ban:{banId}:expired (see AUTH4D-384 (repository file docs/api-spec/auth4d-384.md)).
  • application_id is always null and context is empty: bans are project-wide, so only endpoints without an application filter receive them.
  • event_id is derived from the tenant, the type and an action key: ban:{banId}:banned, ban:{banId}:updated:{updated_at} and ban:{banId}:unbanned. A ban is created and lifted at most once, and each change has its own updated_at, so a retried publish reuses the id.

Delivery

Delivery is best effort, as for every other event: a queue failure is logged as flows.publish_failed with only type and tenant_id, and never fails the request.

Console

The webhook form lists user.banned as Player banned, user.ban_updated as Ban changed and user.unbanned as Ban lifted, and selects them by default for new endpoints. Existing endpoints keep their stored event types.

Source: docs/api-spec/auth4d-362.md