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).
Info:

Event types and payloads are documented per product: Chat events, Feeds events, Video events and Moderation events.

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"],
    },
  ],
});

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
    },
  ],
});
Warning:

Updating event_hooks replaces the whole array. Any previously existing hooks not included in the update will be deleted, so get the current app settings first and send back the complete list including your new hook.

Info:

For reliable event delivery, you can also configure SQS or SNS instead of webhooks.

Adding a Hook Without Deleting Existing Ones

An event_hooks update replaces the whole array: any previously existing hooks not included in it will be deleted. To add a hook, fetch the current configuration first and include the existing hooks in the update. The same pattern applies to SQS and SNS hooks.

// 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 webhook hook while preserving existing hooks
const existingHooks = response.event_hooks || [];
const newWebhookHook = {
  enabled: true,
  hook_type: "webhook",
  webhook_url: "https://example.com/webhooks/stream/push",
  event_types: [], // empty array = all events
};

// STEP 3: Update with complete array including existing hooks
await client.updateAppSettings({
  event_hooks: [...existingHooks, newWebhookHook],
});

// Test the webhook connection
await client.testWebhookSettings({
  webhook_url: "https://example.com/webhooks/stream/push",
});

Debugging webhook requests with NGROK

The easiest way to debug webhooks is with NGROK.

  1. Start NGROK
brew install ngrok
ngrok http 8000

  1. Update your webhook URL to the NGROK url

  2. Trigger a webhook

  3. 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:

Name Description Example
X-Webhook-Id Unique ID of the webhook call. This value is consistent between retries and could be used to deduplicate retry calls 123e4567-e89b-12d3-a456-426614174000
X-Webhook-Attempt Number of webhook request attempt starting from 1 1
X-Api-Key Your application's API key. Should be used to validate request signature a1b23cdefgh4
X-Signature HMAC signature of the request body. See Signature section ca978112ca1bbdcafac231b39a23dc4da786eff8147c4e72b9807785afee48bb

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:

Language Error class Failure-mode messages
JavaScript InvalidWebhookError signature mismatch, invalid base64 encoding, gzip decompression failed, invalid JSON payload
Python InvalidWebhookError same
Ruby StreamChat::Webhook::InvalidWebhookError same
PHP InvalidWebhookException same (InvalidWebhookException::SIGNATURE_MISMATCH etc.)
Go sentinel getstream.ErrInvalidWebhook same prefixes; use errors.Is(err, getstream.ErrInvalidWebhook) for the unified check
Java io.getstream.Webhook.InvalidWebhookError same (Webhook.InvalidWebhookError.SIGNATURE_MISMATCH etc.)
.NET (C#) StreamInvalidWebhookException same (StreamInvalidWebhookException.SignatureMismatch etc.)

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
}

Where each argument comes from

Argument Source Example
body / rawBody Raw HTTP request body bytes (not a parsed JSON object) req.rawBody, request.body, request.data, r.Body (drained)
signature X-Signature request header req.headers["x-signature"]

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

Warning:

Pass the raw body bytes, before any JSON parsing or string normalization. The helper hashes them as-is. In Express, enable express.raw({ type: 'application/json' }); in Django use request.body; in Flask use request.data; in Go drain r.Body once and reuse the bytes. If your framework hands you a parsed object, the signature check fails.

Note:

No client handy? Every SDK also ships the same logic as a stateless static / module-level helper that takes the API secret as an explicit third argument. The instance method is a thin wrapper around it, so the two forms behave identically; pick whichever fits the call site (Lambdas, edge functions, queue consumers, tests).

// 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#.

Retries

When a delivery fails, Stream retries it immediately, with no backoff. Retries stop as soon as any one of these limits is reached:

Limit Value
Attempts per event 5
Timeout per attempt 6 seconds
Total time per event, including all retries 15 seconds
Retryable response errors (408, 429, any 5xx) 3
Network errors 2

Attempt timeouts have a ceiling of their own, set to 5, but with these values the 15 second total budget is always reached first. Two attempts that time out consume 12 seconds, and a third starts and is cut short when the budget runs out, so an endpoint that never answers sees three attempts rather than five.

Any other non-2xx response is treated as final and is not retried. Retry-After is not honoured. Every retry carries the same X-Webhook-Id with an incrementing X-Webhook-Attempt, so deduplicate on the ID rather than on event contents.

These limits are per hook and identical for every product: chat, feeds, video and moderation events all follow them.

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.

Info:

Apps created after May 7, 2026 have enable_hook_payload_compression set to true by default. Your handlers will receive compressed payloads out of the box, so make sure they call verifyAndParseWebhook on HTTP traffic and parse_sqs / parse_sns on queue/topic deliveries (or equivalent decode + parse_event primitives) before going live. Apps created before that date stay opt-in; run the snippet below to turn compression on.

Enabling compression

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

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 threshold is 256 bytes. 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 an SQS queue, use the event_hooks array and the 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 SQS hook while preserving existing hooks
const existingHooks = response.event_hooks || [];
const newSQSHook = {
  enabled: true,
  hook_type: "sqs",
  sqs_queue_url: "https://sqs.us-east-1.amazonaws.com/123456789012/MyQueue",
  sqs_region: "us-east-1",
  sqs_auth_type: "keys", // or "resource" for role-based auth
  sqs_key: "yourkey",
  sqs_secret: "yoursecret",
  event_types: [], // empty array = all events
};

// STEP 3: Update with complete array including existing hooks
await client.updateAppSettings({
  event_hooks: [...existingHooks, newSQSHook],
});

// Test the SQS connection
await client.testSQSSettings();

Configuration Options

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

Option Type Description Required
id string Unique identifier for the event hook No. If empty, it will generate an ID.
enabled boolean Boolean flag to enable/disable the hook Yes
hook_type string Must be set to "sqs" Yes
sqs_queue_url string The AWS SQS queue URL Yes
sqs_region string The AWS region where the SQS queue is located (e.g., "us-east-1") Yes
sqs_auth_type string Authentication type: "keys" for access key/secret or "resource" for role-based auth Yes
sqs_key string AWS access key ID (required if auth_type is "keys") Yes if using key auth
sqs_secret string AWS secret access key (required if auth_type is "keys") Yes if using key auth
event_types array Array of event types this hook should handle No. Not provided or empty array means subscribe to all existing and future events.

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

Here's an example list of messages read from your SQS queue:

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).

Note:

No X-Signature on SQS. Stream does not ship an HMAC signature on SQS deliveries. The transport is authenticated end-to-end: the queue is gated by IAM, so only your account can read it, and only Stream's account can write to it.

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

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.

Building this without a Stream SDK? Expand the per-language reference implementation below.

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.

  • Set up alerts in case the size of the queue is growing too fast.

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 an SNS topic, use the event_hooks array and the 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",
});

Configuration Options

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

Option Type Description Required
id string Unique identifier for the event hook No. If empty, it will generate an ID.
enabled boolean Boolean flag to enable/disable the hook Yes
hook_type string Must be set to "sns" Yes
sns_topic_arn string The AWS SNS topic ARN Yes
sns_region string The AWS region where the SNS topic is located (e.g., "us-east-1") Yes
sns_auth_type string Authentication type: "keys" for access key/secret or "resource" for role-based auth Yes
sns_key string AWS access key ID (required if auth_type is "keys") Yes if using key auth
sns_secret string AWS secret access key (required if auth_type is "keys") Yes if using key auth
event_types array Array of event types this hook should handle No. Not provided or empty array means subscribe to all existing and future events.

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.

Note:

No Stream X-Signature on SNS. Stream does not ship an app-level HMAC on SNS payloads. SNS itself is authenticated with AWS signatures (SigningCertURL / Signature) when you subscribe over HTTPS.

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

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).

Building this without a Stream SDK? Expand the per-language reference implementation below.

SNS Best practices and Assumptions

  • Set the maximum message size set to 256 KB.

Messages bigger than the maximum message size will be dropped.

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.

Google Cloud Storage (GCS) and Amazon S3 are supported as failover storage backends. Failover can be configured on webhook, SQS, and SNS hooks.

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 storage bucket
  3. The event is stored as a JSON file containing the full event payload, metadata about the failure, and the original endpoint

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

Failover is configured on the hook, not per product, so a hook subscribed to feeds.*, call.* or moderation.* event types behaves exactly like the chat example below.

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":"..."}',
      },
    },
  ],
});
Warning:

GCS credentials are validated when you save the configuration. Make sure the service account JSON key is valid and has write access to the specified bucket before updating your app settings.

The same failover_config works on SQS and SNS hooks. This example uses an S3 bucket as the failover destination instead:

await client.updateAppSettings({
  event_hooks: [
    {
      enabled: true,
      hook_type: "sqs",
      sqs_queue_url: "https://sqs.us-east-1.amazonaws.com/1111111111/my-queue",
      sqs_auth_type: "role",
      sqs_role_arn: "arn:aws:iam::1111111111:role/stream-events",
      event_types: ["message.new"],
      failover_config: {
        type: "s3",
        s3_bucket: "my-failover-bucket",
        s3_path: "stream/failed-events",
        s3_region: "us-east-1",
        // Recommended: a role in your account that Stream assumes
        // (see S3 Permissions below for the trust policy). Alternatively
        // set s3_api_key + s3_secret to use a dedicated access key pair.
        s3_role_arn: "arn:aws:iam::1111111111:role/stream-event-failover",
      },
    },
  ],
});

Configuration Options

Option Type Description Required
type string Storage backend type: "gcs" or "s3" Yes
gcs_bucket string The name of your GCS bucket With type: "gcs"
gcs_credentials string GCS service account JSON key as a string With type: "gcs"
gcs_path string Optional prefix for the object path inside the bucket No
s3_bucket string The name of your S3 bucket With type: "s3"
s3_region string AWS region of the bucket, e.g. us-east-1 With type: "s3"
s3_role_arn string ARN of a role in your AWS account that Stream assumes to write failed events. Cannot be combined with s3_api_key/s3_secret One auth mode: s3_role_arn or the key pair
s3_api_key string AWS access key ID. Set together with s3_secret One auth mode: s3_role_arn or the key pair
s3_secret string AWS secret access key. Set together with s3_api_key With s3_api_key
s3_path string Optional prefix for the object path inside the bucket No

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.

S3 Permissions

S3 supports two authentication modes. They are mutually exclusive — configure exactly one:

  • IAM role (recommended): set s3_role_arn to a role in your AWS account. Stream assumes it with your app ID as the STS External ID, so no long-lived credentials change hands and you can revoke access at any time by editing the role's trust policy.
  • Access keys: set s3_api_key and s3_secret to a key pair whose IAM policy allows s3:PutObject on the bucket.

IAM role setup

Create a role in your account with a permissions policy allowing s3:PutObject on the bucket, and the following trust policy. The sts:ExternalId condition value is your numeric app ID (shown in the Stream Dashboard URL and returned by Get App Settings); it protects the role against use on behalf of any other Stream application:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowStreamEventFailover",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::185583345998:root"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "YOUR_APP_ID"
        }
      }
    }
  ]
}
Warning:

Unlike GCS credentials, S3 access is not probed when you save the configuration. A misconfigured trust policy or key pair only surfaces when the first failed event is written, so verify bucket access independently before relying on failover. A missing bucket or an access denial on the upload itself is not retried, but failures assuming your role are retried for several hours — so fixing a trust policy promptly still lets already-captured events land.

Storage Format

Failed events are stored as JSON files in your bucket with the following path structure (the prefix is your gcs_path or s3_path, omitted when unset):

{path}/{yyyy}/{mm}/{dd}/{timestamp}-{event_type}-{webhook_id}.json

webhook_id is the per-delivery identifier — the X-Webhook-ID header value for webhook deliveries, or a generated UUID for SQS and SNS — not the ID of the hook itself. The hook's ID is inside the envelope as original_hook_id.

For example:

stream/failed-events/2026/04/03/1743667200-message.new-a1b2c3d4.json

Each file contains a JSON envelope with the following fields:

Field Description
original_hook_id The ID of the event hook that failed
original_target The endpoint that was unreachable: the webhook URL, SQS queue URL, or SNS topic ARN
original_webhook_url Deprecated alias of original_target, kept for consumers of existing archives
hook_type The transport of the failed hook: webhook, sqs, or sns. Absent on events archived before this field existed
event_type The type of event that failed to deliver
error_message The error returned by the last delivery attempt
failed_at ISO 8601 timestamp of when the failure was recorded
payload The full event payload that would have been delivered

Example envelope:

{
  "original_hook_id": "hook-123",
  "original_target": "https://example.com/webhooks/stream",
  "original_webhook_url": "https://example.com/webhooks/stream",
  "hook_type": "webhook",
  "event_type": "message.new",
  "error_message": "HTTP 500: Internal Server Error",
  "failed_at": "2026-04-03T12:00:00Z",
  "payload": {
    "type": "message.new",
    "cid": "messaging:general",
    "message": { ... },
    "user": { ... }
  }
}

Two behaviours to design your consumer around:

  • A 403 from your endpoint is read as a deliberate rejection rather than an outage. That event is dropped and is not written to failover storage. Return a 5xx, or time out, for anything you want kept for replay.
  • payload holds the bare event JSON, not the HTTP envelope. Envelope-level fields that live delivery adds, such as request_info, are absent from the stored copy.

The stored payload is always plain event JSON, regardless of the app-level enable_hook_payload_compression flag described under Payload Compression — failover archives the event before wire compression is applied, so a consumer reading failed events from your bucket never needs to gzip-decompress. You can still feed the payload field through the same verifyAndParseWebhook helper you use for live webhooks (see the reference implementation); it passes plain JSON through unchanged.

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
    },
  ],
});

Request info

Info:

Treat request_info as optional. Chat, feeds and moderation events carry it, but only when the event came from an HTTP request. Events emitted by background work ship without the field entirely rather than with an empty object, as do the copies written by event failover, which store the bare event JSON.

Some webhooks contain a field request_info , which holds information about the client that issued the request. This info is intended as an additional signal that you can use for moderation, fraud detection, or other similar purposes.

When configuring the SDK, you may also set an additional x-stream-ext header to be sent with each request. The value of this header is passed along as an ext field in the request_info . You can use this to pass along information that may be useful, such as device information. Refer to the SDK-specific docs on how to set this header, since the option differs by SDK and the server-side SDKs do not expose custom request headers at all. For feeds, see Adding your own data to ext.

"request_info": {
 "type": "client",
 "ip": "86.84.2.2",
 "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:109.0) Gecko/20100101 Firefox/117.0",
 "sdk": "stream-chat-react-10.11.0-stream-chat-javascript-client-browser-8.12.1",
 "ext": "device-id=123"
}

For example, in Javascript, you can set the value like this:

client = new StreamChat(apiKey, {
  axiosRequestConfig: {
    headers: {
      "x-stream-ext": "device-id=123",
    },
  },
});

The format of the ext header is up to you and you may leave it blank if you don't need it. The value is passed as-is, so you can use a simple value, comma-separated key-values, or more structured data, such as JSON. Binary data must be encoded as a string, for example using base64 or hex encoding.

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. Addresses are never removed or rotated, but new addresses can be added when a region grows, so review this list periodically.

Region IP addresses
us-east4 (US-East) 34.225.10.29/32
34.198.125.61/32
52.22.78.160/32
3.215.161.238/32
34.181.149.154/32
34.145.214.228/32
34.182.155.177/32
34.21.94.53/32
us-east5 (Ohio) 3.14.163.216/32
3.15.245.3/32
3.141.116.179/32
34.186.254.218/32
34.186.255.37/32
34.162.4.149/32
8.234.63.48/32
34.187.36.107/32
34.187.49.94/32
us-west1 (Oregon) 52.25.165.25/32
44.237.58.11/32
52.10.213.81/32
8.229.163.173/32
136.117.241.8/32
northamerica-northeast1 (Canada) 35.183.141.98/32
52.60.71.231/32
3.97.253.35/32
34.19.168.136/32
34.19.229.75/32
europe-west4 (EU-West) 52.212.14.212/32
52.17.43.232/32
34.241.110.177/32
35.204.6.219/32
34.158.68.88/32
europe-west2 (London) 3.11.74.113/32
3.10.181.72/32
13.42.218.244/32
34.153.181.194/32
34.142.62.7/32
asia-south1 (Mumbai) 65.1.48.87/32
15.206.221.25/32
13.233.48.78/32
34.93.113.218/32
34.47.139.79/32
asia-southeast1 (Singapore) 13.229.11.158/32
52.74.225.150/32
52.76.180.70/32
35.187.232.235/32
35.185.180.233/32
australia-southeast1 (Sydney) 54.252.193.245/32
13.55.254.141/32
3.24.48.104/32
34.151.136.126/32
34.116.110.249/32

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.

Add Chat to my app: getstream.io/SKILL.md

The fastest way to build with Stream. Start a new project or improve an existing one. Full CLI and documentation integration out of the box.

Ask your agent:

/stream Build me a Social App with Feeds and Moderation.
/stream Any livestream calls running?
/stream Platform: <Your Question>