SNS

Stream can send payloads of all events from your application to an Amazon SNS topic you own.

A chat application with a lot of users generates a lots of events. With a standard Webhook configuration, events are posted to your server and can overwhelm unprepared servers during high-use periods. While the server is out, it will not be able to receive Webhooks and will fail to process them. One way to avoid this issue is to use Stream Chat’s support for sending webhooks to Amazon SNS.

SNS removes the chance of losing data for Chat events by providing a large, scalable message exchange that delivers events generated by Stream Chat to as many consumers as you like.

The complete list of supported events is identical to those sent through webhooks and can be found on the Events page.

Configuration

You can configure your SNS topic through the Stream Dashboard or using the Dashboard or programmatically using the REST API or an SDK with Server Side Authorization.

There are 2 ways to configure authentication on your SNS topic:

1. By providing a key and secret

2. Or by having Stream’s AWS account assume a role on your SNS topic. With this option you omit the key and secret, but instead you set up a resource-based policy to grant Stream Publish permission on your SNS topic. The following policy needs to be attached to your topic (replace the value of Resource with the fully qualified ARN of your topic):

{  "Sid": "AllowStreamProdAccount",  "Effect": "Allow",  "Principal": {  "AWS": "arn:aws:iam::185583345998:root"  },  "Action": "SNS:Publish",  "Resource": "arn:aws:sns:us-west-2:1111111111:customer-sns-topic" }

Using the Dashboard

1. Go to the Stream Dashboard
2. Select your app
3. Navigate to your app’s settings until “Webhook & Event Configuration” section
4. Click on “Add Integration”
5. Add and configure SNS hook

At this point, you can click Test SNS to have Stream’s servers test their connection with SNS and report back.

Using Server-Side SDKs

To configure an SNS topic, use the event_hooks array and Update App Settings method:

// Note: Any previously existing hooks not included in event_hooks array will be deleted. // Get current settings first to preserve your existing configuration.  // STEP 1: Get current app settings to preserve existing hooks const response = await client.getAppSettings(); console.log("Current event hooks:", response.event_hooks);  // STEP 2: Add SNS hook while preserving existing hooks const existingHooks = response.event_hooks || []; const newSNSHook = {  enabled: true,  hook_type: "sns",  sns_topic_arn: "arn:aws:sns:us-east-1:123456789012:sns-topic",  sns_region: "us-east-1",  sns_auth_type: "keys", // or "resource" for role-based auth  sns_key: "yourkey",  sns_secret: "yoursecret",  event_types: [], // empty array = all events };  // STEP 3: Update with complete array including existing hooks await client.updateAppSettings({  event_hooks: [...existingHooks, newSNSHook], });  // Test the SNS connection await client.testSNSSettings({  sns_topic_arn: "arn:aws:sns:us-east-1:123456789012:sns-topic",  sns_key: "yourkey",  sns_secret: "yoursecret", });

# Note: Any previously existing hooks not included in event_hooks array will be deleted. # Get current settings first to preserve your existing configuration.  # STEP 1: Get current app settings to preserve existing hooks response = client.get_app_settings() existing_hooks = response.get("event_hooks", []) print("Current event hooks:", existing_hooks)  # STEP 2: Add SNS hook while preserving existing hooks new_sns_hook = {  "enabled": True,  "hook_type": "sns",  "sns_topic_arn": "arn:aws:sns:us-east-1:123456789012:sns-topic",  "sns_region": "us-east-1",  "sns_auth_type": "keys", # or "resource" for role-based auth  "sns_key": "yourkey",  "sns_secret": "yoursecret",  "event_types": [] # empty array = all events }  # STEP 3: Update with complete array including existing hooks client.update_app_settings(  event_hooks=existing_hooks + [new_sns_hook] )  # Test the SNS connection client.check_sns("yourkey", "yoursecret", "arn:aws:sns:us-east-1:123456789012:sns-topic")

# Note: Any previously existing hooks not included in event_hooks array will be deleted. # Get current settings first to preserve your existing configuration.  # STEP 1: Get current app settings to preserve existing hooks response = client.get_app_settings existing_hooks = response["event_hooks"] || [] puts "Current event hooks:", existing_hooks  # STEP 2: Add SNS hook while preserving existing hooks new_sns_hook = {  "enabled" => true,  "hook_type" => "sns",  "sns_topic_arn" => "arn:aws:sns:us-east-1:123456789012:sns-topic",  "sns_region" => "us-east-1",  "sns_auth_type" => "keys", # or "resource" for role-based auth  "sns_key" => "yourkey",  "sns_secret" => "yoursecret",  "event_types" => [] # empty array = all events }  # STEP 3: Update with complete array including existing hooks client.update_app_settings(  event_hooks: existing_hooks + [new_sns_hook] )  # Test the SNS connection client.check_sns('yourkey', 'yoursecret', 'arn:aws:sns:us-east-1:123456789012:sns-topic')

// Note: Any previously existing hooks not included in event_hooks array will be deleted. // Get current settings first to preserve your existing configuration.  // STEP 1: Get current app settings to preserve existing hooks $response = $client->getAppSettings(); $existingHooks = $response['event_hooks'] ?? []; echo "Current event hooks: " . json_encode($existingHooks);  // STEP 2: Add SNS hook while preserving existing hooks $newSNSHook = [  'enabled' => true,  'hook_type' => 'sns',  'sns_topic_arn' => 'arn:aws:sns:us-east-1:123456789012:sns-topic',  'sns_region' => 'us-east-1',  'sns_auth_type' => 'keys', // or 'resource' for role-based auth  'sns_key' => 'yourkey',  'sns_secret' => 'yoursecret',  'event_types' => [] // empty array = all events ];  // STEP 3: Update with complete array including existing hooks $client->updateAppSettings([  'event_hooks' => array_merge($existingHooks, [$newSNSHook]) ]);  // Test the SNS connection $client->checkSns([  'sns_topic_arn' => 'arn:aws:sns:us-east-1:123456789012:sns-topic',  'sns_key' => 'yourkey',  'sns_secret' => 'yoursecret' ]);

// Note: Any previously existing hooks not included in event_hooks array will be deleted. // Get current settings first to preserve your existing configuration.  // STEP 1: Get current app settings to preserve existing hooks settings, err := client.GetAppSettings(ctx) if err != nil {  log.Fatal(err) } existingHooks := settings.App.EventHooks fmt.Printf("Current event hooks: %+v\n", existingHooks)  // STEP 2: Add SNS hook while preserving existing hooks newSNSHook := EventHook{  HookType: SNSHook,  Enabled: true,  EventTypes: []string{}, // empty slice = all events  SNSTopicARN: "arn:aws:sns:us-east-1:123456789012:sns-topic",  SNSRegion: "us-east-1",  SNSAuthType: "keys", // or "resource" for role-based auth  SNSKey: "yourkey",  SNSSecret: "yoursecret", }  // STEP 3: Update with complete array including existing hooks allHooks := append(existingHooks, newSNSHook) _, err = client.UpdateAppSettings(ctx, NewAppSettings().SetEventHooks(allHooks)) if err != nil {  log.Fatal(err) }  // Test the SNS connection req := &CheckSNSRequest{  SnsTopicArn: "arn:aws:sns:us-east-1:123456789012:sns-topic",  SnsKey: "yourkey",  SnsSecret: "yoursecret", } client.CheckSns(ctx, req)

// Note: Any previously existing hooks not included in event_hooks array will be deleted. // Get current settings first to preserve your existing configuration.  // STEP 1: Get current app settings to preserve existing hooks App.AppGetResponse response = App.get().request(); List<App.EventHook> existingHooks = response.getApp().getEventHooks(); System.out.println("Current event hooks: " + existingHooks);  // STEP 2: Add SNS hook while preserving existing hooks App.EventHook newSNSHook = new App.EventHook(); newSNSHook.setHookType(App.HookType.SNS); newSNSHook.setEnabled(true); newSNSHook.setEventTypes(Collections.emptyList()); // empty list = all events newSNSHook.setSnsTopicARN("arn:aws:sns:us-east-1:123456789012:sns-topic"); newSNSHook.setSnsRegion("us-east-1"); newSNSHook.setSnsAuthType(App.AuthType.KEYS); // or RESOURCE for role-based auth newSNSHook.setSnsKey("yourkey"); newSNSHook.setSnsSecret("yoursecret");  // STEP 3: Update with complete array including existing hooks List<App.EventHook> allHooks = new ArrayList<>(existingHooks); allHooks.add(newSNSHook); App.update().eventHooks(allHooks).request();  // Test the SNS connection App.checkSns()  .snsKey("yourkey")  .snsSecret("yoursecret")  .snsTopicArn("arn:aws:sns:us-east-1:123456789012:sns-topic")  .request();

// Note: Any previously existing hooks not included in event_hooks array will be deleted. // Get current settings first to preserve your existing configuration.  // STEP 1: Get current app settings to preserve existing hooks var settings = await client.GetAppSettingsAsync(); var existingHooks = settings.App.EventHooks ?? new List<EventHook>(); Console.WriteLine($"Current event hooks: {existingHooks}");  // STEP 2: Add SNS hook while preserving existing hooks var newSNSHook = new EventHook {  HookType = HookType.SNS,  Enabled = true,  EventTypes = new List<string>(), // empty list = all events  SnsTopicArn = "arn:aws:sns:us-east-1:123456789012:sns-topic",  SnsRegion = "us-east-1",  SnsAuthType = AuthType.Keys, // or Resource for role-based auth  SnsKey = "yourkey",  SnsSecret = "yoursecret" };  // STEP 3: Update with complete array including existing hooks var allHooks = new List<EventHook>(existingHooks) { newSNSHook }; await client.UpdateAppSettingsAsync(new AppSettingsRequest {  EventHooks = allHooks });  // Test the SNS connection await appClient.CheckSnsPushAsync(new AppCheckSnsRequest {  SnsKey = "yourkey",  SnsSecret = "yoursecret",  SnsTopicArn = "arn:aws:sns:us-east-1:123456789012:sns-topic", });

See the Multi-Event Hooks documentation for complete details.

SNS Best practices and Assumptions

• Set the maximum message size set to 256 KB.

Messages bigger than the maximum message size will be dropped.