Real-Time Events via WebSocket Subscriptions

CA Colombia delivers real-time updates over WebSocket subscriptions rather than traditional HTTP webhooks. Once connected, your client subscribes to one or more named topics and receives event messages as users and characters are created, updated, or deleted. This page documents the payload formats for every event topic. For instructions on establishing a connection and authenticating, see the WebSocket guide.

Event Message Structure

Every message delivered over the WebSocket connection shares the same envelope structure. The channel field identifies which topic the event belongs to, type is always "event" for data events, and data contains the topic-specific payload.

{
  "channel": "characters:update",
  "type": "event",
  "data": { ... }
}

Field	Type	Description
`channel`	`string`	The subscription topic that produced this event.
`type`	`string`	Message type. Data events always use `"event"`.
`data`	`object`	The event payload. Shape varies by topic — see sections below.

Your client should check the type field of every incoming message and handle only "event" messages for topic data. Messages with other type values, or error objects without a type field, should be handled or silently ignored as appropriate.

User Events

User events notify you when an account is created, its profile is modified, or it is removed from the platform. Subscribe to one or more of the following topics:

Topic	When it fires
`users:create`	A new user account has been created.
`users:update`	An existing user’s profile or settings have changed.
`users:delete`	A user account has been deleted.

The data payload for all user events contains the updated state of the user object at the time the event was emitted, including the user’s ID, permissions, linked providers, and active character reference. Example — users:update event:

{
  "channel": "users:update",
  "type": "event",
  "data": {
    "userId": "123456789012345678",
    "permissions": 1024,
    "maxCharacters": 3,
    "activeCharacter": "987654321098765432",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-06-20T14:45:00.000Z"
  }
}

Character Events

Character events notify you when a character is created, modified, or removed. Subscribe to one or more of the following topics:

Topic	When it fires
`characters:create`	A new character has been created.
`characters:update`	A character’s data or approval status has changed.
`characters:delete`	A character has been deleted.

The data payload for character events contains the full character object. The fields included are:

Field	Type	Description
`userId`	`string`	Snowflake ID of the user who owns this character.
`characterId`	`string`	Unique Snowflake ID for this character.
`firstNames`	`string`	The character’s first name(s).
`lastNames`	`string`	The character’s last name(s).
`age`	`number`	The character’s age.
`height`	`number`	The character’s height.
`gender`	`string`	`"Masculino"` or `"Femenino"`.
`bloodType`	`string`	One of `O+`, `O-`, `A+`, `A-`, `B+`, `B-`, `AB+`, `AB-`.
`nationality`	`object`	Object containing `nombre`, `abrev`, and `lugar` fields.
`dob`	`string`	Date of birth in `DD/MM/YYYY` format.
`avatarHash`	`string \| null`	Hash of the character’s avatar image.
`idCardHash`	`string \| null`	Hash of the generated ID card image.
`fullBodyHash`	`string \| null`	Hash of the full-body image.
`avatar3dHash`	`string \| null`	Hash of the 3D avatar asset.
`idStatus`	`string`	Approval state: `"draft"`, `"submitted"`, `"approved"`, or `"rejected"`.
`wallet`	`object \| null`	The character’s wallet object if one exists, otherwise `null`.
`createdAt`	`string`	ISO 8601 timestamp of when the character was created.
`updatedAt`	`string`	ISO 8601 timestamp of the last update.

Example — characters:create event:

{
  "channel": "characters:create",
  "type": "event",
  "data": {
    "userId": "123456789012345678",
    "characterId": "234567890123456789",
    "firstNames": "Carlos",
    "lastNames": "Rodríguez",
    "age": 28,
    "height": 175,
    "gender": "Masculino",
    "bloodType": "O+",
    "nationality": {
      "nombre": "Colombiana",
      "abrev": "COL",
      "lugar": "Colombia"
    },
    "dob": "15/03/1996",
    "avatarHash": null,
    "idCardHash": null,
    "fullBodyHash": null,
    "avatar3dHash": null,
    "idStatus": "draft",
    "wallet": null,
    "createdAt": "2024-06-20T14:45:00.000Z",
    "updatedAt": "2024-06-20T14:45:00.000Z"
  }
}

Subscribe to characters:update to detect when a character’s idStatus changes from "submitted" to "approved" or "rejected". This is the recommended way to react to staff approval decisions in real time without polling the REST API.

Subscribing to Topics

Subscribe only to the topics your application actually needs. Every active subscription adds to the volume of messages your client must process. Receiving unnecessary events — especially on high-traffic topics like characters:update — can increase latency and memory usage in your integration.

See the WebSocket guide for the exact subscribe message format and how to manage your active subscriptions over the lifetime of a connection.

Get Started

Core Concepts

Guides

Reference

Real-Time Events via WebSocket Subscriptions

Event Message Structure

User Events

Character Events

Subscribing to Topics

​Event Message Structure

​User Events

​Character Events

​Subscribing to Topics

Event Message Structure

User Events

Character Events

Subscribing to Topics