Receiving Events

Receive real-time events over WebSocket connections

Event Structure

All events received over WebSocket follow this JSON structure:

{
  "event": "my-event",
  "channel": "my-channel",
  "data": "{\"message\":\"Hello World\"}"
}

event · string · required

The event name (max 200 characters)

channel · string

The channel this event was published to. Omitted for connection-level events.

data · string

Event payload as a JSON-encoded string. Can be any valid JSON.

Event Types

Events are categorized into three types:

1. System Events

Internal events prefixed with pusher: or pusher_internal:. These manage connection and subscription lifecycle.

Connection Events:

• pusher:connection_established - Sent when connection opens
• pusher:error - Error notification
• pusher:ping - Keep-alive ping from server
• pusher:pong - Keep-alive pong response

Subscription Events:

• pusher_internal:subscription_succeeded - Channel subscription confirmed
• pusher_internal:member_added - User joined presence channel
• pusher_internal:member_removed - User left presence channel

2. Application Events

Custom events triggered via the REST API or webhooks. These are your application’s business logic events.

{
  "event": "order-placed",
  "channel": "orders",
  "data": "{\"order_id\":\"12345\",\"amount\":99.99}"
}

3. Client Events

Events sent directly between clients on private/presence channels. Prefixed with client-.

{
  "event": "client-typing",
  "channel": "presence-chat-room",
  "data": "{\"user\":\"Alice\"}"
}

See Client Events for details.

Data Field Format

The data field is always a JSON-encoded string, even if the original data was an object.

Parsing Data

Clients must parse the data string to access the payload:

// Received event
const event = {
  event: 'price-update',
  channel: 'ticker:BTC',
  data: '{"price":50000,"change":1.5}'
};

// Parse the data
const payload = JSON.parse(event.data);
console.log(payload.price); // 50000
console.log(payload.change); // 1.5

Empty Data

Some events have no payload and use an empty object:

{
  "event": "pusher:ping",
  "data": null
}

Presence Events

Presence channels emit special events when users join or leave:

Member Added

{
  "event": "pusher_internal:member_added",
  "channel": "presence-chat-room",
  "data": "{\"user_id\":\"123\",\"user_info\":{\"name\":\"Alice\"}}"
}

data.user_id · string

The ID of the user who joined

data.user_info · object

Optional user metadata provided during subscription

Member Removed

{
  "event": "pusher_internal:member_removed",
  "channel": "presence-chat-room",
  "data": "{\"user_id\":\"123\"}"
}

data.user_id · string

The ID of the user who left

Event Filtering

If you subscribed with a tag filter, you only receive events matching your filter criteria:

// Subscribe with filter
channel.subscribe('sports-events', {
  filter: { eq: ['sport', 'soccer'] }
});

// Only receive events with tag sport=soccer
{
  "event": "goal-scored",
  "channel": "sports-events",
  "data": "{\"team\":\"Arsenal\",\"player\":\"Saka\"}"
  // Tags are stripped by server (if enable_tags: false)
}

See Tag Filtering for details.

Delta Compressed Events

If delta compression is enabled, some events are sent as deltas:

{
  "event": "pusher:delta",
  "channel": "ticker:BTC",
  "data": "{\"channel\":\"ticker:BTC\",\"event\":\"price-update\",\"delta\":\"base64-encoded-delta\",\"base_seq\":10,\"target_seq\":11,\"algorithm\":\"fossil\"}"
}

data.event · string

The original event name

data.delta · string

Base64-encoded binary delta patch

data.base_seq · integer

Sequence number of the base message

data.target_seq · integer

Sequence number of the reconstructed message

data.algorithm · string

Delta algorithm used: “fossil” or “xdelta3”

See Delta Compression for details.

Example: Handling Events with pusher-js

import Pusher from 'pusher-js';

const pusher = new Pusher('your-app-key', {
  wsHost: 'localhost',
  wsPort: 6001,
  forceTLS: false
});

const channel = pusher.subscribe('notifications');

// Bind to specific event
channel.bind('new-message', (data) => {
  // pusher-js automatically parses the data field
  console.log('New message:', data.text);
  console.log('From:', data.sender);
});

// Bind to all events on channel
channel.bind_global((event, data) => {
  console.log('Event received:', event, data);
});

// Presence channel events
const presenceChannel = pusher.subscribe('presence-chat');

presenceChannel.bind('pusher:subscription_succeeded', (members) => {
  console.log('Current members:', members.count);
});

presenceChannel.bind('pusher:member_added', (member) => {
  console.log('User joined:', member.id, member.info);
});

presenceChannel.bind('pusher:member_removed', (member) => {
  console.log('User left:', member.id);
});

Event Name Rules

• Maximum length: 200 characters
• System events are prefixed with pusher: or pusher_internal:
• Client events must be prefixed with client-
• Application events can use any name not starting with pusher:, pusher_internal:, or client-
• Event names are case-sensitive

Error Events

When errors occur, the server sends a pusher:error event:

{
  "event": "pusher:error",
  "data": {
    "code": 4009,
    "message": "Channel requires authentication"
  },
  "channel": "private-user-123"
}

Common error codes:

Code	Description
4000	Generic error
4001	Application does not exist
4004	Application disabled
4005	Origin not allowed
4009	Connection/subscription timeout
4100	Buffer full - slow consumer

Watchlist Events

If you’ve subscribed to a user watchlist, you receive online/offline events:

{
  "event": "online",
  "data": {
    "user_ids": ["user-123", "user-456"]
  }
}

{
  "event": "offline",
  "data": {
    "user_ids": ["user-789"]
  }
}

See Watchlists for details.