Activity Feeds V3 is in closed alpha — do not use it in production (just yet).

Event Handling

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.

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:

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
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
© Getstream.io, Inc. All Rights Reserved.