Webhooks

Every Stream product can deliver events to your server using webhooks, SQS or SNS. When setting up a hook you can specify the exact events you want to receive, or select to receive all events.

To ensure that a webhook is triggered by Stream you can verify its signature. Webhook retries are in place. If you want to ensure an outage in your API never loses an event, it's better to use SQS or SNS for reliability.

The configuration can be done using the API or from 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).

Configuring Hooks

Here's how to quickly set up webhooks using the event_hooks configuration:

Subscribe to Specific Events

// Subscribe to message.new and message.updated events only
await client.updateAppSettings({
  event_hooks: [
    {
      enabled: true,
      hook_type: "webhook",
      webhook_url: "https://example.com/webhooks/stream/messages",
      event_types: ["message.new", "message.updated"],
    },
  ],
});

from getstream.models import EventHook

# Subscribe to message.new and message.updated events only
client.update_app(
    event_hooks=[
        EventHook(
            enabled=True,
            hook_type="webhook",
            webhook_url="https://example.com/webhooks/stream/messages",
            event_types=["message.new", "message.updated"],
        )
    ]
)

require 'getstream_ruby'
Models = GetStream::Generated::Models

# Subscribe to message.new and message.updated events only
client.common.update_app(Models::UpdateAppRequest.new(
  event_hooks: [
    {
      'enabled' => true,
      'hook_type' => 'webhook',
      'webhook_url' => 'https://example.com/webhooks/stream/messages',
      'event_types' => ['message.new', 'message.updated']
    }
  ]
))

// Subscribe to message.new and message.updated events only
$client->updateApp(new Models\UpdateAppRequest(
    eventHooks: [
        new Models\EventHook(
            enabled: true,
            hookType: "webhook",
            webhookUrl: "https://example.com/webhooks/stream/messages",
            eventTypes: ["message.new", "message.updated"],
        ),
    ],
));

// Subscribe to message.new and message.updated events only
client.UpdateApp(ctx, &getstream.UpdateAppRequest{
  EventHooks: []getstream.EventHook{
    {
      HookType:   getstream.PtrTo("webhook"),
      Enabled:    getstream.PtrTo(true),
      EventTypes: []string{"message.new", "message.updated"},
      WebhookUrl: getstream.PtrTo("https://example.com/webhooks/stream/messages"),
    },
  },
})

// Subscribe to message.new and message.updated events only
var webhookHook = new EventHook
{
    HookType = "webhook",
    Enabled = true,
    EventTypes = new List<string> { "message.new", "message.updated" },
    WebhookUrl = "https://example.com/webhooks/stream/messages",
};

await client.UpdateAppAsync(new UpdateAppRequest
{
    EventHooks = new List<EventHook> { webhookHook },
});

// Subscribe to message.new and message.updated events only
var webhookHook = EventHook.builder()
    .hookType("webhook")
    .enabled(true)
    .eventTypes(List.of("message.new", "message.updated"))
    .webhookUrl("https://example.com/webhooks/stream/messages")
    .build();

client.updateApp(UpdateAppRequest.builder()
    .eventHooks(List.of(webhookHook))
    .build()).execute();

Subscribe to All Events

Use an empty event_types array to receive all existing and future events:

// Subscribe to all events (empty array = all events)
await client.updateAppSettings({
  event_hooks: [
    {
      enabled: true,
      hook_type: "webhook",
      webhook_url: "https://example.com/webhooks/stream/all",
      event_types: [], // empty array = all events
    },
  ],
});

from getstream.models import EventHook

# Subscribe to all events (empty list = all events)
client.update_app(
    event_hooks=[
        EventHook(
            enabled=True,
            hook_type="webhook",
            webhook_url="https://example.com/webhooks/stream/all",
            event_types=[],  # empty list = all events
        )
    ]
)

require 'getstream_ruby'
Models = GetStream::Generated::Models

# Subscribe to all events (empty array = all events)
client.common.update_app(Models::UpdateAppRequest.new(
  event_hooks: [
    {
      'enabled' => true,
      'hook_type' => 'webhook',
      'webhook_url' => 'https://example.com/webhooks/stream/all',
      'event_types' => [] # empty array = all events
    }
  ]
))

// Subscribe to all events (empty array = all events)
$client->updateApp(new Models\UpdateAppRequest(
    eventHooks: [
        new Models\EventHook(
            enabled: true,
            hookType: "webhook",
            webhookUrl: "https://example.com/webhooks/stream/all",
            eventTypes: [], // empty array = all events
        ),
    ],
));

// Subscribe to all events (empty slice = all events)
client.UpdateApp(ctx, &getstream.UpdateAppRequest{
  EventHooks: []getstream.EventHook{
    {
      HookType:   getstream.PtrTo("webhook"),
      Enabled:    getstream.PtrTo(true),
      EventTypes: []string{}, // empty slice = all events
      WebhookUrl: getstream.PtrTo("https://example.com/webhooks/stream/all"),
    },
  },
})

// Subscribe to all events (empty list = all events)
var webhookHook = new EventHook
{
    HookType = "webhook",
    Enabled = true,
    EventTypes = new List<string>(), // empty list = all events
    WebhookUrl = "https://example.com/webhooks/stream/all",
};

await client.UpdateAppAsync(new UpdateAppRequest
{
    EventHooks = new List<EventHook> { webhookHook },
});

// Subscribe to all events (empty list = all events)
var webhookHook = EventHook.builder()
    .hookType("webhook")
    .enabled(true)
    .eventTypes(Collections.emptyList()) // empty list = all events
    .webhookUrl("https://example.com/webhooks/stream/all")
    .build();

client.updateApp(UpdateAppRequest.builder()
    .eventHooks(List.of(webhookHook))
    .build()).execute();

Debugging webhook requests with NGROK

The easiest way to debug webhooks is with NGROK.

1. Start NGROK

brew install ngrok
ngrok http 8000

2. Update your webhook URL to the NGROK url

3. Trigger a webhook

4. Open up the ngrok inspector

http://127.0.0.1:4040/inspect/http

Handling the Webhook

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
• be idempotent. Stream retries on network or 5xx errors, and retried calls carry the same X-Webhook-Id header
• run over HTTPS with Keep-Alive enabled

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)

All webhook requests contain these headers:

Verifying and Parsing Events

To verify and parse the event, call verifyAndParseWebhook on your Stream client. It transparently decompresses the body when Payload Compression is on (detected from the body bytes, so it works behind middleware that auto-decompresses the request) and verifies the HMAC X-Signature header using the API secret the client was constructed with. Every SDK returns a typed event object. Unknown event types fall back to an UnknownEvent shape so your handler keeps working when Stream introduces new ones.

Every failure mode (signature mismatch, gzip decompression failure, base64 decode failure, JSON parse failure) raises a single, language-idiomatic webhook error so you only need one catch arm. The message text identifies which mode fired, so callers that want to differentiate (security logging, retry policy) can filter on it:

Pass the raw body bytes and the X-Signature header value. The client already knows your API secret, so the call stays a two-argument one-liner.

// rawBody is the request body as Buffer or string (NOT a parsed JSON object).
// signature is the value of the x-signature header.
// Returns the parsed event object. Throws InvalidWebhookError on any failure.
try {
  const event = client.verifyAndParseWebhook(
    req.rawBody,
    req.headers["x-signature"],
  );
  // event.type, event.user, ...
} catch (err) {
  // err instanceof InvalidWebhookError; err.message identifies the mode
}

# Django request
event = client.verify_and_parse_webhook(
    request.body,
    request.META["HTTP_X_SIGNATURE"],
)

# Flask request
event = client.verify_and_parse_webhook(
    request.data,
    request.headers["X-Signature"],
)

# event.type, event.user, ...

# request_body is the raw request body string/bytes.
# signature is the value of the x-signature header.
event = client.verify_and_parse_webhook(request_body, signature)
# event.type, event.user, ...

// $requestBody is the raw request body string.
// $signature is the value of the x-signature header.
$event = $client->verifyAndParseWebhook($requestBody, $signature);
// $event['type'], $event['user'], ...

// body is the raw request body bytes.
// signature is the value of the x-signature header.
event, err := client.VerifyAndParseWebhookBytes(body, signature)
if err != nil {
    if errors.Is(err, getstream.ErrInvalidWebhook) {
        // err.Error() contains the failure mode (e.g. "signature mismatch", "invalid base64 encoding")
    }
    return
}
// event.Type, event.User, ...

// Or, for net/http handlers that already have an *http.Request, use the
// legacy convenience form that drains the body and reads X-Signature itself:
//   event, err := client.VerifyAndParseWebhook(r)

// requestBody is the raw request body bytes.
// signature is the value of the x-signature header.
var ev = client.VerifyAndParseWebhook(requestBody, signature);
// ev.Type, ev.User, ...

// body is the raw request body bytes.
// signature is the value of the x-signature header.
var event = client.verifyAndParseWebhook(body, signature);
// event.getType(), event.getUser(), ...

Where each argument comes from

The API secret comes from the client you constructed at startup, so it's never passed into the helper.

// JavaScript (getstream-node)
import { Webhook } from "@getstream/node";
const event = Webhook.verifyAndParseWebhook(rawBody, signature, secret);

# Python (getstream)
from getstream import webhook
event = webhook.verify_and_parse_webhook(body, signature, secret)

# Ruby (getstream_ruby): static helper exposed under the StreamChat::Webhook module
event = StreamChat::Webhook.verify_and_parse_webhook(body, signature, secret)

// PHP (getstream-php)
$event = \GetStream\Webhook::verifyAndParseWebhook($body, $signature, $secret);

// Go (getstream-go): bytes form
event, err := getstream.VerifyAndParseWebhookBytes(body, signature, secret)

// Or, for net/http handlers, the convenience form that takes the request
// (drains the body and reads X-Signature for you):
//   event, err := getstream.VerifyAndParseWebhook(r, secret)

// C# (getstream-dotnet)
var ev = GetStream.Webhook.VerifyAndParseWebhook(body, signature, secret);

// Java (getstream-java)
var event = io.getstream.Webhook.verifyAndParseWebhook(body, signature, secret);

Building this without a Stream SDK? Expand the per-language reference implementation below. Language tabs cover JavaScript, Python, Ruby, PHP, Go, Java and C#.

const crypto = require("crypto");
const zlib = require("zlib");

const GZIP_MAGIC = Buffer.from([0x1f, 0x8b]);

function gunzipPayload(rawBody) {
  const body = Buffer.isBuffer(rawBody) ? rawBody : Buffer.from(rawBody);
  if (body.length >= 2 && body.subarray(0, 2).equals(GZIP_MAGIC)) {
    return zlib.gunzipSync(body);
  }
  return body;
}

function verifySignature(body, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  const sig = Buffer.from(signature, "utf8");
  const exp = Buffer.from(expected, "utf8");
  return sig.length === exp.length && crypto.timingSafeEqual(sig, exp);
}

function verifyAndParseWebhook(rawBody, signature, secret) {
  const body = gunzipPayload(rawBody);
  if (!verifySignature(body, signature, secret)) {
    throw new Error("invalid webhook signature");
  }
  return JSON.parse(body.toString("utf8"));
}

import gzip, hmac, hashlib, json

GZIP_MAGIC = b"\x1f\x8b"

def gunzip_payload(body: bytes) -> bytes:
    if isinstance(body, str):
        body = body.encode("utf-8")
    return gzip.decompress(body) if body[:2] == GZIP_MAGIC else body

def verify_signature(body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode("utf-8"), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

def verify_and_parse_webhook(body, signature, secret):
    body = gunzip_payload(body)
    if not verify_signature(body, signature, secret):
        raise ValueError("invalid webhook signature")
    return json.loads(body)

require 'json'
require 'openssl'
require 'zlib'
require 'stringio'

GZIP_MAGIC = "\x1f\x8b".b.freeze

def gunzip_payload(body)
  body = body.b
  body.start_with?(GZIP_MAGIC) ? Zlib::GzipReader.new(StringIO.new(body)).read : body
end

def verify_signature(body, signature, secret)
  expected = OpenSSL::HMAC.hexdigest('SHA256', secret, body)
  OpenSSL.fixed_length_secure_compare(expected, signature)
end

def verify_and_parse_webhook(body, signature, secret)
  body = gunzip_payload(body)
  raise 'invalid webhook signature' unless verify_signature(body, signature, secret)
  JSON.parse(body)
end

function gunzipPayload(string $body): string {
    if (substr($body, 0, 2) === "\x1f\x8b") {
        $decoded = gzdecode($body);
        if ($decoded === false) {
            throw new RuntimeException('gzip decode failed');
        }
        return $decoded;
    }
    return $body;
}

function verifySignature(string $body, string $signature, string $secret): bool {
    return hash_equals(hash_hmac('sha256', $body, $secret), $signature);
}

function verifyAndParseWebhook(string $body, string $signature, string $secret): array {
    $body = gunzipPayload($body);
    if (!verifySignature($body, $signature, $secret)) {
        throw new RuntimeException('invalid webhook signature');
    }
    return json_decode($body, true, flags: JSON_THROW_ON_ERROR);
}

package webhook

import (
    "bytes"
    "compress/gzip"
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "encoding/json"
    "errors"
    "io"
)

var gzipMagic = []byte{0x1f, 0x8b}

func GunzipPayload(body []byte) ([]byte, error) {
    if len(body) < 2 || !bytes.Equal(body[:2], gzipMagic) {
        return body, nil
    }
    gz, err := gzip.NewReader(bytes.NewReader(body))
    if err != nil {
        return nil, err
    }
    defer gz.Close()
    return io.ReadAll(gz)
}

func VerifySignature(body []byte, signature, secret string) bool {
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write(body)
    expected := []byte(hex.EncodeToString(mac.Sum(nil)))
    return hmac.Equal(expected, []byte(signature))
}

func VerifyAndParseWebhook(body []byte, signature, secret string) (map[string]any, error) {
    body, err := GunzipPayload(body)
    if err != nil {
        return nil, err
    }
    if !VerifySignature(body, signature, secret) {
        return nil, errors.New("invalid webhook signature")
    }
    var event map[string]any
    if err := json.Unmarshal(body, &event); err != nil {
        return nil, err
    }
    return event, nil
}

using System;
using System.IO;
using System.IO.Compression;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;

public static byte[] GunzipPayload(byte[] body)
{
    if (body.Length >= 2 && body[0] == 0x1f && body[1] == 0x8b)
    {
        using var gz = new GZipStream(new MemoryStream(body), CompressionMode.Decompress);
        using var ms = new MemoryStream();
        gz.CopyTo(ms);
        return ms.ToArray();
    }
    return body;
}

public static bool VerifySignature(byte[] body, string signature, string secret)
{
    using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
    var expected = Encoding.UTF8.GetBytes(Convert.ToHexString(hmac.ComputeHash(body)).ToLowerInvariant());
    return CryptographicOperations.FixedTimeEquals(expected, Encoding.UTF8.GetBytes(signature));
}

public static JsonElement VerifyAndParseWebhook(byte[] body, string signature, string secret)
{
    var payload = GunzipPayload(body);
    if (!VerifySignature(payload, signature, secret))
    {
        throw new InvalidOperationException("invalid webhook signature");
    }
    return JsonSerializer.Deserialize<JsonElement>(payload);
}

import java.io.ByteArrayInputStream;
import java.io.ByteArrayOutputStream;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.util.HexFormat;
import java.util.zip.GZIPInputStream;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;

public static byte[] gunzipPayload(byte[] body) throws Exception {
    if (body.length >= 2 && body[0] == 0x1f && (body[1] & 0xff) == 0x8b) {
        try (var gz = new GZIPInputStream(new ByteArrayInputStream(body));
             var out = new ByteArrayOutputStream()) {
            gz.transferTo(out);
            return out.toByteArray();
        }
    }
    return body;
}

public static boolean verifySignature(byte[] body, String signature, String secret) throws Exception {
    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
    byte[] expected = HexFormat.of().formatHex(mac.doFinal(body)).getBytes(StandardCharsets.UTF_8);
    return MessageDigest.isEqual(expected, signature.getBytes(StandardCharsets.UTF_8));
}

public static JsonNode verifyAndParseWebhook(byte[] body, String signature, String secret) throws Exception {
    byte[] payload = gunzipPayload(body);
    if (!verifySignature(payload, signature, secret)) {
        throw new SecurityException("invalid webhook signature");
    }
    return new ObjectMapper().readTree(payload);
}

Retries

In case of the request failure Stream 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.

When delivery fails after all retry attempts, event failover can persist the failed event to a storage backend you control.

Payload Compression

Enable gzip compression for hook payloads with enable_hook_payload_compression. Compressed payloads are typically 70-90% smaller and the decompression cost is negligible. HTTP webhooks get a Content-Encoding: gzip header; SQS and SNS messages are gzipped and base64-wrapped (because both transports are UTF-8 only). The verifyAndParseWebhook helper (HTTP) and parseSqs / parseSns (SQS/SNS, no app-level HMAC) detect the encoding from the body bytes, so the same handler code works whether or not compression is on, and stays correct even when middleware (Rails, Django, Laravel, Phoenix) auto-decompresses the request.

Enabling compression

await client.updateAppSettings({
  enable_hook_payload_compression: true,
});

client.update_app(enable_hook_payload_compression=True)

require 'getstream_ruby'
Models = GetStream::Generated::Models

client.common.update_app(Models::UpdateAppRequest.new(
  enable_hook_payload_compression: true,
))

$client->updateApp(new Models\UpdateAppRequest(
    enableHookPayloadCompression: true,
));

client.UpdateApp(ctx, &getstream.UpdateAppRequest{
  EnableHookPayloadCompression: getstream.PtrTo(true),
})

await client.UpdateAppAsync(new UpdateAppRequest
{
    EnableHookPayloadCompression = true,
});

client.updateApp(UpdateAppRequest.builder()
    .enableHookPayloadCompression(true)
    .build()).execute();

The flag applies to every transport: HTTP webhooks, SQS and SNS. It also covers the event failover hook and chat's Before Message Send hook.

Before enabling compression in production

• Use a current SDK: verifyAndParseWebhook for HTTP (decompress + verify_signature + typed event) and parse_sqs / parse_sns for SQS/SNS (decode + typed event, no app-level HMAC). All three handle uncompressed, gzipped, and base64+gzipped payloads without caller-side branching.
• Without an SDK, your handler must accept Content-Encoding: gzip and gzip-decompress the body; for SQS/SNS, base64-decode then gzip-decompress (or detect via the gzip magic bytes 1f 8b, per RFC 1952).
• Verify HMAC on the uncompressed bytes, never on the gzipped or base64-wrapped envelope.
• Small payloads stay uncompressed to avoid envelope overhead, even with the flag on. The composite helpers handle both cases transparently.

SQS

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

An application with a lot of users generates a lot 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's support for sending webhooks to Amazon SQS.

SQS removes the chance of losing data by providing a large, scalable bucket that holds events generated by Stream in a queue for your server. The complete list of supported events is identical to those sent through webhooks.

Authentication

There are 2 ways to configure authentication on your SQS queue:

1. By providing a key and secret

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

{
  "Sid": "AllowStreamProdAccount",
  "Effect": "Allow",
  "Principal": {
    "AWS": "arn:aws:iam::185583345998:root"
  },
  "Action": "SQS:SendMessage",
  "Resource": "arn:aws:sqs:us-west-2:1111111111:customer-sqs-for-stream"
}

To configure the queue, add a hook with hook_type: "sqs" to the event_hooks array, the same way as the webhook examples above. The full walkthrough lives on the Chat SQS page; the same calls work for every product.

Configuration Options

The following options are available when configuring an SQS event hook:

SQS Permissions

Stream needs the right permissions on your SQS queue to be able to send events to it. If updates are not showing up in your queue add the following permission policy to the queue:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "Stmt1459523779000",
      "Effect": "Allow",
      "Action": [
        "sqs:GetQueueUrl",
        "sqs:SendMessage",
        "sqs:SendMessageBatch",
        "sqs:GetQueueAttributes"
      ],
      "Resource": ["arn:aws:sqs:region:acc_id:queue_name"]
    }
  ]
}

Reading messages from SQS

SQS honours the same enable_hook_payload_compression flag (see Payload Compression). When compression is on, the message body is gzipped + base64-encoded (SQS only accepts UTF-8) and the producer sets these message attributes:

{
  "content_encoding": "gzip",
  "content_type": "application/json",
  "payload_encoding": "base64"
}

Call parseSqs on your Stream client with the SQS Body string. It reverses the base64 + gzip envelope and returns a typed event (with an UnknownEvent fallback), the same shape verifyAndParseWebhook returns for HTTP. The same call works whether or not compression is on (encoding is detected from the body bytes, so the content_encoding / payload_encoding attributes are only a hint).

// message is the SQS Message object you received from ReceiveMessageCommand
const event = client.parseSqs(message.Body);
// event.type, event.user, ...

# message is an SQS message dict from boto3 receive_message
event = client.parse_sqs(message["Body"])
# event.type, event.user, ...

event = client.parse_sqs(message.body)

$event = $client->parseSqs($message['Body']);

event, err := client.ParseSqs(*message.Body)

var ev = client.ParseSqs(message.Body);

var event = client.parseSqs(message.body());

parse_sqs takes only the message body. No HMAC is involved; use your API secret only for other Stream API calls, not for parsing SQS payloads. The same decode + parse logic is exposed as a static / module-level parse_sqs (see Verifying and Parsing Events for per-language imports); use it in workers that don't keep a Stream client around. A per-language reference implementation for SDK-less consumers lives on the Chat SQS page.

SQS Best practices and Assumptions

• Set the maximum message size set to 256 KB.

Messages bigger than the maximum message size will be dropped.

• Set up a dead-letter queue for your main queue.

This queue will hold the messages that couldn't be processed successfully and is useful for debugging your application.

SNS

Stream can send payloads of all events from your application to an Amazon SNS topic you own. SNS provides a large, scalable message exchange that delivers events generated by Stream to as many consumers as you like. The complete list of supported events is identical to those sent through webhooks.

Authentication

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"
}

To configure the topic, add a hook with hook_type: "sns" to the event_hooks array, the same way as the webhook examples above. The full walkthrough lives on the Chat SNS page; the same calls work for every product.

Configuration Options

The following options are available when configuring an SNS event hook:

Reading notifications from SNS

SNS honours the same enable_hook_payload_compression flag (see Payload Compression). When compression is on, the notification Message is gzipped + base64-encoded (SNS only accepts UTF-8) and the producer sets the same message attributes as SQS.

Call parseSns on your Stream client with the notification body (either the raw envelope JSON string or the pre-extracted Message field). It unwraps the SNS envelope when needed, reverses the base64 + gzip payload, and returns a typed event. The return shape matches verifyAndParseWebhook sans verification. The same call works whether or not compression is on, and whether the topic is delivered over HTTP or via an SQS subscription.

const event = client.parseSns(notification.Message);
// event.type, event.user, ...

event = client.parse_sns(notification["Message"])
# event.type, event.user, ...

event = client.parse_sns(notification['Message'])

$event = $client->parseSns($notification['Message']);

event, err := client.ParseSns(notification.Message)

var ev = client.ParseSns(notification.Message);

var event = client.parseSns(notification.getMessage());

parse_sns takes only the notification body string. No HMAC is involved; use your API secret only for other Stream API calls. The same unwrap + decode + parse logic is exposed as a static / module-level parse_sns (see Verifying and Parsing Events for per-language imports). A per-language reference implementation for SDK-less consumers lives on the Chat SNS page.

Event Failover

When event delivery fails after all retry attempts, Stream can automatically persist the failed event to a storage backend you control. This ensures no events are lost during outages in your endpoint.

Currently, Google Cloud Storage (GCS) is supported as a failover storage backend.

How it Works

1. Stream attempts to deliver an event to your endpoint
2. If all delivery retries are exhausted, the event is written to your configured GCS bucket
3. The event is stored as a JSON file containing the full event payload, metadata about the failure, and the original endpoint URL

You can then process these failed events at your own pace by reading them from GCS.

Configuration

To enable failover, add a failover_config to your event hook:

await client.updateAppSettings({
  event_hooks: [
    {
      enabled: true,
      hook_type: "webhook",
      webhook_url: "https://example.com/webhooks/stream",
      event_types: ["message.new"],
      failover_config: {
        type: "gcs",
        gcs_bucket: "my-failover-bucket",
        gcs_path: "stream/failed-events",
        gcs_credentials: '{"type":"service_account","project_id":"..."}',
      },
    },
  ],
});

Configuration Options

GCS Permissions

The service account used in gcs_credentials needs the following permissions on the target bucket:

• storage.objects.create
• storage.objects.get

The simplest way is to grant the Storage Object Creator (roles/storage.objectCreator) role to the service account on the bucket.

Storage Format

Failed events are stored as JSON files in your GCS bucket with the following path structure:

{gcs_path}/{yyyy}/{mm}/{dd}/{timestamp}-{event_type}-{hook_id}.json

Each file contains a JSON envelope with the following fields:

Event failover honours the same app-level enable_hook_payload_compression flag described under Payload Compression. If you build a consumer that reads failed events from your GCS bucket, feed the payload field through the same verifyAndParseWebhook helper you use for live webhooks (or the manual gunzip_payload + parse_event primitives from the reference implementation) so your code transparently handles both the plain-JSON and the compressed cases.

Disabling Failover

To remove the failover configuration, update the hook without the failover_config field:

await client.updateAppSettings({
  event_hooks: [
    {
      enabled: true,
      hook_type: "webhook",
      webhook_url: "https://example.com/webhooks/stream",
      event_types: [],
      // no failover_config = failover disabled
    },
  ],
});

Restricting Access to Webhook

If necessary, you can only expose your webhook service to Stream. This is possible by configuring your network (eg. iptables rules) to drop all incoming traffic that is not coming from our API infrastructure.

Below you can find the complete list of egress IP addresses that our webhook infrastructure uses. Such list is static and is not changing over time.

Product-Specific Hooks

Chat has additional hook types that are configured outside the event_hooks system: Before Message Send for modifying or moderating messages before delivery, Custom Commands for reacting to /slash commands, and pending messages for approval flows. Push delivery to user devices is covered under push notifications.