Trigger Event

Trigger a single event to one or more channels

POST /apps/{appId}/events

Trigger Event

cURL

curl --request POST \
  --url https://api.example.com/apps/{appId}/events \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "data": {},
  "channel": "<string>",
  "channels": [
    {}
  ],
  "socket_id": "<string>",
  "info": "<string>",
  "tags": {},
  "delta": true
}
'

200

{
  "ok": true,
  "channels": {
    "subscription_count": 123,
    "user_count": 123
  }
}

Authentication

All HTTP API requests must be authenticated using HMAC-SHA256 signatures. Authentication can be provided via:

1. Query parameters (recommended):

   • auth_key - Your application key
   • auth_timestamp - Unix timestamp (must be within 10 minutes of server time)
   • auth_version - Always “1.0”
   • auth_signature - HMAC-SHA256 signature
   • body_md5 - MD5 hash of request body (required for POST with non-empty body)

2. Authorization header: Authorization: key:signature

Generating Signatures

The signature is computed from:

POST\n/apps/{appId}/events\nauth_key={key}&auth_timestamp={timestamp}&auth_version=1.0&body_md5={md5}

All query parameters (except auth_signature) are sorted alphabetically and lowercased before signing.

Path Parameters

appId · string · required

The application ID

Request Body

name · string · required

Event name (max length configurable per app, default 200 characters)

data · string | object · required

Event payload. Can be a JSON string or object. Size limited by max_event_payload_in_kb app setting.

channel · string

Single channel name. Either channel or channels must be provided.

channels · array

Array of channel names. Limited by max_event_channels_at_once app setting. Either channel or channels must be provided.

socket_id · string

Socket ID to exclude from receiving the event (optional)

info · string

Comma-separated list of attributes to include in response:

• subscription_count - Number of connections subscribed to each channel
• user_count - Number of unique users (presence channels only)

tags · object

Key-value pairs for server-side filtering (requires tag_filtering.enabled: true). Tags are used for filtering but can be optionally stripped from messages sent to clients.

delta · boolean

Per-message delta compression control:

• true - Force delta compression for this message (if client supports it)
• false - Force full message (skip delta compression)
• Omit to use channel/global configuration default

Response

ok · boolean

true if the event was triggered successfully (returned when info is not requested)

channels · object

Channel information object (returned when info parameter is provided)

Show Channel Info

subscription_count · number

Number of active subscriptions to the channel

user_count · number

Number of unique users (presence channels only, when info includes user_count)

Rate Limiting

Responses include rate limit headers:

• X-RateLimit-Limit - Maximum requests allowed per window
• X-RateLimit-Remaining - Requests remaining in current window
• X-RateLimit-Reset - Seconds until rate limit resets
• Retry-After - Seconds to wait before retrying (when rate limited)

Examples

Simple Event

curl -X POST "https://api.example.com/apps/my-app/events?auth_key=key&auth_timestamp=1234567890&auth_version=1.0&body_md5=fc820aa38714282f8300c2ca039cd034&auth_signature=abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "order-update",
    "channel": "orders",
    "data": "{\"order_id\": 123, \"status\": \"shipped\"}"
  }'

Response Examples

Success (No Info)

{
  "ok": true
}

Error Codes

Status Code	Description
200	Success
400	Bad Request (invalid parameters, limit exceeded)
401	Unauthorized (authentication failed)
404	Application not found
413	Payload Too Large
429	Too Many Requests (rate limited)
500	Internal Server Error

Notes

• Event names starting with client- are reserved for client events
• Channel names have specific format requirements (see channel validation)
• Private and presence channels require authenticated subscriptions from clients
• Cache channels (cache-*) automatically cache the last event for new subscribers
• Delta compression can significantly reduce bandwidth for similar consecutive messages (60-90% typical savings)
• Tags enable server-side filtering with minimal overhead (12-94ns per filter evaluation)