Event Handling

The state layer provides a way to be notified about state updates easily. However, it's also possible to watch for WebSocket events directly, should you need it.

Available Event Types

Below is a comprehensive table of all available event types and their descriptions:

Feed events

Feed events are related to a specific feed. This is how you can subscribe to them:

// Watch for a specific event
const unsubscribe = feed.on("feeds.activity.added", (event) =>
  console.log(event),
);

// Watch for all events
const unsubscribe = feed.on("all", (event) => console.log(event));

To receive feed event, you need to watch the feed:

const feed = client.feed("user", "sara");
// Provide the watch flag to receive state updates via WebSocket events
await feed.getOrCreate({ watch: true });

// Query multiple feeds using a filter
const feeds = client.queryFeeds({
  filter: {
    // Your query
  },
  // Provide the watch flag to receive state updates via WebSocket events
  watch: true,
});

Activity events

When reading an activity outside of a feed, you can only watch for WebSocket events, if the feed the activity belongs to is watched:

const activityWithStateUpdates =
  client.activityWithStateUpdates(activityId);
await activityWithStateUpdates.get({
  // Optionally fetch comments too
  comments: {
    limit: 10,
    depth: 2,
  },
});

// Optionally start watching the feed
// If activity belongs to multiple feeds, it's up to you to choose which feed to watch
const fid = activityWithStateUpdates.currentState.activity!.feeds[0];
const [group, id] = fid.split(':');
const feed = client.feed(group, id);
let shouldWatch = false;
if (!feed.currentState.watch) {
  await feed.getOrCreate({
    watch: true,
    limit: 0,
    followers_pagination: { limit: 0 },
    following_pagination: { limit: 0 },
  });
}

const unsubscribe = activityWithStateUpdates.on("feeds.activity.updated", (event) =>
  console.log(event),
);

Client events

Client events contain

• all events related to currently watched feeds
• all poll vote events related to currently watched feeds
• events related to a specific user (for example bookmark event)
• events related to network connection

// Watch for a specific event
const unsubscribe = client.on("connection.changed", (event) =>
  console.log(event),
);

// Watch for all events
const unsubscribe = client.on("all", (event) =>
  console.log(`Client is ${event.online ? "online" : "offline"}`),
);

Server-side webhooks

Webhooks are configured with your API secret, so they belong on your backend rather than in the app you ship. Setting up an endpoint, verifying signatures, retries and event failover are covered under Event handling in the server-side docs, with the full transport reference in the platform webhooks guide.

Adding your own data to ext

Events delivered to your backend carry a request_info object describing the client that caused them: auth type, IP, user agent and SDK version. The ext field is the one you control. Whatever you send in the x-stream-ext header arrives on the event unchanged, so use it for context the payload does not otherwise carry, such as a device identifier or an app build number.

Set it as a custom header when you construct the client:

import { FeedsClient } from "@stream-io/feeds-react-sdk";

const client = new FeedsClient("<API key>", {
  custom_headers: { "x-stream-ext": "device-id=abc123" },
});

import { FeedsClient } from "@stream-io/feeds-client";

const client = new FeedsClient("<API key>", {
  custom_headers: { "x-stream-ext": "device-id=abc123" },
});

The value is passed through as-is, so the format is yours to pick: a bare value, comma-separated pairs, or JSON. Encode binary data as a string, for example with base64 or hex. Reserved headers such as Authorization and X-Stream-Client always win, so a custom header cannot overwrite them. Custom headers apply to API requests only, not to the WebSocket connection.

custom_headers requires @stream-io/feeds-client 2.7.0 or later, and the matching React and React Native SDK releases.

The payload your backend receives is documented under Request info.