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}/banspublishesuser.bannedonce the ban row is written, the player’s sessions are revoked and the audit event is appended. When sessions were revoked, the existingsession.revoked(reason: "admin") is still published as well.PATCH /management/tenants/{tenantId}/users/{userId}/bans/{banId}publishesuser.ban_updatedafter an active ban is changed, including a change to the reason only.POST /management/tenants/{tenantId}/users/{userId}/bans/{banId}/revokepublishesuser.unbannedonly when this request lifted the ban (revoked: true). Revoking a ban that was already revoked answersrevoked: falseand publishes nothing.- Nothing is published for a refused request: an invalid body (400),
ban_activeortoo_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.unbannedfrom the lifecycle cron, up to about 10 minutes late, under the action keyban:{banId}:expired(see AUTH4D-384 (repository filedocs/api-spec/auth4d-384.md)). application_idis alwaysnullandcontextis empty: bans are project-wide, so only endpoints without an application filter receive them.event_idis derived from the tenant, the type and an action key:ban:{banId}:banned,ban:{banId}:updated:{updated_at}andban:{banId}:unbanned. A ban is created and lifted at most once, and each change has its ownupdated_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