Event Handling

This document explains how to listen to real-time events from Stream Feeds using the FeedsClient event publisher.

Overview

The FeedsClient provides two ways to listen to events:

  1. All Events: Listen to all events and handle them with type checking
  2. Specific Event Types: Listen to only specific event types for type-safe handling

Listening to All Events

Use the main eventPublisher to receive all events and handle them with type checking:

import Combine
import StreamFeeds

class MyViewController: UIViewController {
    @State private var cancellables = Set<AnyCancellable>()
    let feedsClient: FeedsClient

    override func viewDidLoad() {
        super.viewDidLoad()
        setupEventListening()
    }

    private func setupEventListening() {
        feedsClient.eventPublisher
            .sink { event in
                self.handleEvent(event)
            }
            .store(in: &cancellables)
    }

    private func handleEvent(_ event: Event) {
        switch event {
        case let activityEvent as ActivityAddedEvent:
            print("πŸ“ New activity: \(activityEvent.activity.id)")
            updateFeedUI()

        case let pollEvent as PollClosedFeedEvent:
            print("πŸ“Š Poll closed: \(pollEvent.poll.id)")
            refreshPollData()

        case let commentEvent as CommentAddedEvent:
            print("πŸ’¬ New comment: \(commentEvent.comment.id)")
            updateCommentsUI()

        case let reactionEvent as ActivityReactionAddedEvent:
            print("πŸ‘ Reaction added: \(reactionEvent.reaction.kind)")
            updateReactionsUI()

        case let followEvent as FollowCreatedEvent:
            print("πŸ‘₯ New follow: \(followEvent.follow.target)")
            updateFollowCount()

        case let bookmarkEvent as BookmarkAddedEvent:
            print("πŸ”– Bookmark added: \(bookmarkEvent.bookmark.id)")
            updateBookmarksUI()

        case let feedEvent as FeedCreatedEvent:
            print("πŸ“‹ Feed created: \(feedEvent.fid)")
            refreshFeedList()

        case let connectedEvent as ConnectedEvent:
            print("πŸ”— Connected to Stream with ID: \(connectedEvent.connectionId)")

        case let errorEvent as ConnectionErrorEvent:
            print("❌ Connection error: \(errorEvent.error)")
            handleConnectionError()

        default:
            print("πŸ“‘ Received event: \(type(of: event))")
        }
    }
}

Listening to Specific Event Types

For type-safe event handling, use the generic eventPublisher(for:) method:

class ActivityHandler {
    private var cancellables = Set<AnyCancellable>()
    let feedsClient: FeedsClient

    init(feedsClient: FeedsClient) {
        self.feedsClient = feedsClient
        setupActivityListeners()
    }

    private func setupActivityListeners() {
        // Listen only to activity added events
        feedsClient.eventPublisher(for: ActivityAddedEvent.self)
            .sink { activityEvent in
                print("New activity: \(activityEvent.activity.id)")
                self.handleNewActivity(activityEvent)
            }
            .store(in: &cancellables)

        // Listen only to activity updated events
        feedsClient.eventPublisher(for: ActivityUpdatedEvent.self)
            .sink { activityEvent in
                print("Activity updated: \(activityEvent.activity.id)")
                self.handleActivityUpdate(activityEvent)
            }
            .store(in: &cancellables)

        // Listen only to activity deleted events
        feedsClient.eventPublisher(for: ActivityDeletedEvent.self)
            .sink { activityEvent in
                print("Activity deleted: \(activityEvent.activity.id)")
                self.handleActivityDeletion(activityEvent)
            }
            .store(in: &cancellables)
    }

    private func handleNewActivity(_ event: ActivityAddedEvent) {
        // Handle new activity
    }

    private func handleActivityUpdate(_ event: ActivityUpdatedEvent) {
        // Handle activity update
    }

    private func handleActivityDeletion(_ event: ActivityDeletedEvent) {
        // Handle activity deletion
    }
}

Multiple Event Type Listeners

You can set up multiple listeners for different event types:

class FeedManager {
    private var cancellables = Set<AnyCancellable>()
    let feedsClient: FeedsClient

    init(feedsClient: FeedsClient) {
        self.feedsClient = feedsClient
        setupEventListeners()
    }

    private func setupEventListeners() {
        // Activity events
        feedsClient.eventPublisher(for: ActivityAddedEvent.self)
            .sink { [weak self] event in
                self?.handleActivityAdded(event)
            }
            .store(in: &cancellables)

        // Comment events
        feedsClient.eventPublisher(for: CommentAddedEvent.self)
            .sink { [weak self] event in
                self?.handleCommentAdded(event)
            }
            .store(in: &cancellables)

        // Poll events
        feedsClient.eventPublisher(for: PollVoteCastedFeedEvent.self)
            .sink { [weak self] event in
                self?.handlePollVote(event)
            }
            .store(in: &cancellables)

        // Connection events
        feedsClient.eventPublisher(for: ConnectedEvent.self)
            .sink { [weak self] event in
                self?.handleConnection(event)
            }
            .store(in: &cancellables)
    }
}

SwiftUI Integration

Here's how to listen to events in SwiftUI:

struct FeedView: View {
    @StateObject private var viewModel: FeedViewModel
    @State private var cancellables = Set<AnyCancellable>()

    var body: some View {
        List(viewModel.activities) { activity in
            ActivityRow(activity: activity)
        }
        .onAppear {
            setupEventListening()
        }
        .onDisappear {
            cancellables.removeAll()
        }
    }

    private func setupEventListening() {
        viewModel.feedsClient.eventPublisher(for: ActivityAddedEvent.self)
            .receive(on: DispatchQueue.main)
            .sink { event in
                viewModel.addActivity(event.activity)
            }
            .store(in: &cancellables)

        viewModel.feedsClient.eventPublisher(for: ActivityUpdatedEvent.self)
            .receive(on: DispatchQueue.main)
            .sink { event in
                viewModel.updateActivity(event.activity)
            }
            .store(in: &cancellables)
    }
}

Available Event Types

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

Event NameDescription
Activity Events
ActivityAddedEventFired when a new activity is added to a feed
ActivityUpdatedEventFired when an activity is modified
ActivityDeletedEventFired when an activity is removed
ActivityRestoredEventFired when an activity is restored
ActivityRemovedFromFeedEventFired when an activity is removed from a specific feed
ActivityMarkEventFired when activities are marked as read/seen
ActivityPinnedEventFired when an activity is pinned to the top
ActivityUnpinnedEventFired when an activity is unpinned
Comment Events
CommentAddedEventFired when a new comment is added to an activity
CommentUpdatedEventFired when a comment is modified
CommentDeletedEventFired when a comment is removed
Reaction Events
ActivityReactionAddedEventFired when a reaction is added to an activity
ActivityReactionDeletedEventFired when a reaction is removed from an activity
CommentReactionAddedEventFired when a reaction is added to a comment
CommentReactionDeletedEventFired when a reaction is removed from a comment
Poll Events
PollClosedFeedEventFired when a poll is closed
PollDeletedFeedEventFired when a poll is deleted
PollUpdatedFeedEventFired when a poll is modified
PollVoteCastedFeedEventFired when a vote is cast
PollVoteChangedFeedEventFired when a vote is changed
PollVoteRemovedFeedEventFired when a vote is removed
Feed Events
FeedCreatedEventFired when a new feed is created
FeedUpdatedEventFired when a feed is modified
FeedDeletedEventFired when a feed is deleted
FeedGroupChangedEventFired when a feed group is modified
FeedGroupDeletedEventFired when a feed group is deleted
Member Events
FeedMemberAddedEventFired when a member is added to a feed
FeedMemberRemovedEventFired when a member is removed from a feed
FeedMemberUpdatedEventFired when a member's role/permissions change
Follow Events
FollowCreatedEventFired when a follow relationship is created
FollowDeletedEventFired when a follow relationship is removed
FollowUpdatedEventFired when follow settings are modified
Bookmark Events
BookmarkAddedEventFired when an activity is bookmarked
BookmarkDeletedEventFired when a bookmark is removed
BookmarkUpdatedEventFired when bookmark metadata is modified
Connection Events
ConnectedEventFired when successfully connected to WebSocket
ConnectionErrorEventFired when connection fails or errors occur
HealthCheckEventFired when health check is received

You can configure your Stream app to receive webhook events as well as AWS SNS and AWS SQS. Webhooks are usually the simplest way to receive events from your app and to perform additional action based on what happens to your application.

The configuration can be done using the API or from the Dashboard. By default, all events are sent to your webhook/sqs/sns endpoint, you can also configure the events you want to receive in the dashboard.

await serverAuthClient.updateAppSettings({
  event_hooks: [
    {
      hook_type: "webhook",
      enabled: true,
      // Pass an empty array to subscribe to all events
      event_types: [],
      webhook_url: "<webhook url>",
    },
    {
      hook_type: "webhook",
      enabled: true,
      // Subscribe only to specific events
      event_types: ["feeds.activity.added" /* ... */],
      webhook_url: "<webhook url>",
    },
  ],
});

Some important points to consider:

  • The selection of events you want to receive applies to all the endpoints you have configured.
  • You can configure multiple endpoints for the same app (eg. AWS SNS and HTTP Webhook).
  • If your app is configured to receive all events, you can still filter the events you want to receive in your webhook handler.
  • If your app is configured to receive all events, newly introduced event types will be sent to your webhook handler by default.
  • If you pick specific events, newly introduced event types will not be sent to your webhook handler by default (you can still manually add them later on).

How to implement a webhook handler

Your webhook handler needs to follow these rules:

  • accept HTTP POST requests with JSON payload
  • be reachable from the public internet. Tunneling services like Ngrok are supported
  • respond with response codes from 200 to 299 as fast as possible

Your webhook handler can use the type field to handle events based correctly based on their type and payload.

All webhook requests contain these headers:

NameDescription
X-WEBHOOK-IDUnique ID of the webhook call. This value is consistent between retries and could be used to deduplicate retry calls
X-WEBHOOK-ATTEMPTNumber of webhook request attempt starting from 1
X-API-KEYYour application’s API key. Should be used to validate request signature
X-SIGNATUREHMAC signature of the request body. See Signature section

Best Practices

We highly recommend following common security guidelines to make your webhook integration safe and fast:

  • Use HTTPS with a certificate from a trusted authority
  • Verify the "X-Signature" header to ensure the request is coming from Stream
  • Support HTTP Keep-Alive
  • Use a highly available infrastructure such as AWS Elastic Load Balancer, Google Cloud Load Balancer, or similar
  • Offload the processing of the message if possible (read, store, and forget)
  • When decoding JSON into objects, ensure that your webhook can handle new fields being added to the JSON payload as well as new event types (eg. log unknown fields and event types instead of failing)

Error Handling

In case of the request failure Stream Chat attempts to retry a request. The amount of maximum attempts depends on the kind of the error it receives:

  • Response code is 408, 429 or >=500: 3 attempts
  • Network error: 2 attempts
  • Request timeout: 3 attempts

The timeout of one request is 6 seconds, and the request with all retries cannot exceed the duration of 15 seconds.

Available Event Types

Below is a comprehensive table of all available event types and their descriptions. WebhookEvent model definition can be found in Open API specification.

Event NameDescription
Activity Events
feeds.activity.addedFired when a new activity is added to a feed
feeds.activity.updatedFired when an activity is modified
feeds.activity.deletedFired when an activity is removed
feeds.activity.restoredFired when an activity is restored
feeds.activity.removed_from_feedFired when an activity is removed from a specific feed
feeds.activity.pinnedFired when an activity is pinned to the top
feeds.activity.unpinnedFired when an activity is unpinned
feeds.activity.feedbackFired when activity feedback is provided
feeds.activity.markedFired when an activity is marked
Notification Events
feeds.notification_feed.updatedFired when the notification status, or notification groups (aggregated activities) are updated
Comment Events
feeds.comment.addedFired when a new comment is added to an activity
feeds.comment.updatedFired when a comment is modified
feeds.comment.deletedFired when a comment is removed
Reaction Events
feeds.activity.reaction.addedFired when a reaction is added to an activity
feeds.activity.reaction.deletedFired when a reaction is removed from an activity
feeds.activity.reaction.updatedFired when a reaction on an activity is updated
feeds.comment.reaction.addedFired when a reaction is added to a comment
feeds.comment.reaction.deletedFired when a reaction is removed from a comment
feeds.comment.reaction.updatedFired when a reaction on a comment is updated
Poll Events
feeds.poll.closedFired when a poll is closed
feeds.poll.deletedFired when a poll is deleted
feeds.poll.updatedFired when a poll is modified
feeds.poll.vote_castedFired when a vote is cast
feeds.poll.vote_changedFired when a vote is changed
feeds.poll.vote_removedFired when a vote is removed
Feed Events
feeds.feed.createdFired when a new feed is created
feeds.feed.updatedFired when a feed is modified
feeds.feed.deletedFired when a feed is deleted
Feed Group Events
feeds.feed_group.changedFired when a feed group is changed
feeds.feed_group.deletedFired when a feed group is deleted
Member Events
feeds.feed_member.addedFired when a member is added to a feed
feeds.feed_member.removedFired when a member is removed from a feed
feeds.feed_member.updatedFired when a member's role/permissions change
Follow Events
feeds.follow.createdFired when a follow relationship is created
feeds.follow.deletedFired when a follow relationship is removed
feeds.follow.updatedFired when follow settings are modified
Bookmark Events
feeds.bookmark.addedFired when an activity is bookmarked
feeds.bookmark.deletedFired when a bookmark is removed
feeds.bookmark.updatedFired when bookmark metadata is modified
feeds.bookmark_folder.deletedFired when bookmark folder is deleted
feeds.bookmark_folder.updatedFired when bookmark folder is updated
Stories Events
feeds.stories_feed.updatedFired when a stories feed is updated
Moderation Events
moderation.custom_actionFired when a custom moderation action is performed
moderation.flaggedFired when content is flagged for moderation
moderation.mark_reviewedFired when content is marked as reviewed
User Events
user.bannedFired when a user is banned
user.deactivatedFired when a user is deactivated
user.mutedFired when a user is muted
user.reactivatedFired when a user is reactivated
user.updatedFired when a user is updated