Webhooks Overview

You can listen to events using webhooks, SQS or SNS. When setting up a webhook 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 it's 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.

Quick Start

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 = 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 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 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 = 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();

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

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 endpoint should accept POST requests with JSON, return a 2xx response on success, be idempotent (Stream retries on network or 5xx errors), and run over HTTPS with Keep-Alive enabled.

To verify and parse the event, call verifyAndParseWebhook on your chat 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 against 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.message, 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.message, 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.message, 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['message'], $event['user'], ...

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

// 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.Message, 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.getMessage(), event.getUser(), ...

Where each argument comes from

The API secret comes from the client you constructed at startup (new StreamChat(apiKey, apiSecret) and friends), 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)
event, err := getstream.VerifyAndParseWebhook(body, signature, 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
}

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

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

All webhook requests contain these headers:

Payload Compression

Enable gzip compression for hook payloads from the Dashboard or 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),
})

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

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

The flag applies to every transport: HTTP webhooks, SQS, SNS, the Before Message Send hook, and the event failover 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.

Webhook types

In addition to the above there are 3 special webhooks.

Configuration

Before Message Send and Custom Commands

These webhooks continue to use the original configuration method and are NOT part of the multi-event hooks system:

• Before Message Send: before_message_send_hook_url
• Custom Commands: custom_action_handler_url

await client.updateAppSettings({
  before_message_send_hook_url:
    "https://example.com/webhooks/stream/before-message-send", // sets Before Message Send webhook address
  custom_action_handler_url:
    "https://example.com/webhooks/stream/custom-commands?type={type}", // sets Custom Commands webhook address
});

client.update_app(
    before_message_send_hook_url="https://example.com/webhooks/stream/before-message-send", # sets Before Message Send webhook address
    custom_action_handler_url="https://example.com/webhooks/stream/custom-commands?type={type}", # sets Custom Commands webhook address
)

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

client.common.update_app(Models::UpdateAppRequest.new(
  before_message_send_hook_url: 'https://example.com/webhooks/stream/before-message-send', # sets Before Message Send webhook address
  custom_action_handler_url: 'https://example.com/webhooks/stream/custom-commands?type={type}' # sets Custom Commands webhook address
))

$client->updateApp(new Models\UpdateAppRequest(
    beforeMessageSendHookUrl: "https://example.com/webhooks/stream/before-message-send", // sets Before Message Send webhook address
    customActionHandlerUrl: "https://example.com/webhooks/stream/custom-commands?type={type}", // sets Custom Commands webhook address
));

client.updateApp(UpdateAppRequest.builder()
    .beforeMessageSendHookUrl("https://example.com/webhooks/stream/before-message-send") // sets Before Message Send webhook address
    .customActionHandlerUrl("https://example.com/webhooks/stream/custom-commands?type={type}") // sets Custom Commands webhook address
    .build()).execute();

await client.UpdateAppAsync(new UpdateAppRequest
{
    BeforeMessageSendHookUrl = "https://example.com/webhooks/stream/before-message-send", // sets Before Message Send webhook address
    CustomActionHandlerUrl = "https://example.com/webhooks/stream/custom-commands?type={type}", // sets Custom Commands webhook address
});

client.UpdateApp(ctx, &getstream.UpdateAppRequest{
  BeforeMessageSendHookUrl: getstream.PtrTo("https://example.com/webhooks/stream/before-message-send"), // sets Before Message Send webhook address
  CustomActionHandlerUrl:   getstream.PtrTo("https://example.com/webhooks/stream/custom-commands?type={type}"), // sets Custom Commands webhook address
})

Push webhook

The example below shows how to use the push webhooks

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

from getstream.models import EventHook

# 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()
existing_hooks = response.data.app.event_hooks or []
print("Current event hooks:", existing_hooks)

# STEP 2: Add webhook hook while preserving existing hooks
new_webhook_hook = EventHook(
    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
client.update_app(
    event_hooks=existing_hooks + [new_webhook_hook]
)

# Test webhook delivery using the Stream Dashboard

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

# 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.common.get_app
existing_hooks = response.app.event_hooks || []
puts "Current event hooks:", existing_hooks

# STEP 2: Add webhook hook while preserving existing hooks
new_webhook_hook = {
  '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
client.common.update_app(Models::UpdateAppRequest.new(
  event_hooks: existing_hooks + [new_webhook_hook]
))

# Test the webhook connection
client.common.check_push(Models::CheckPushRequest.new)

// 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->getApp();
$existingHooks = $response->getData()->app->eventHooks ?? [];

// STEP 2: Add webhook hook while preserving existing hooks
$newWebhookHook = new Models\EventHook(
    enabled: true,
    hookType: "webhook",
    webhookUrl: "https://example.com/webhooks/stream/push",
    eventTypes: [], // empty array = all events
);

// STEP 3: Update with complete array including existing hooks
$client->updateApp(new Models\UpdateAppRequest(
    eventHooks: array_merge($existingHooks, [$newWebhookHook]),
));

// 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.GetApp(ctx, &getstream.GetAppRequest{})
if err != nil {
    log.Fatal(err)
}
existingHooks := settings.Data.App.EventHooks

// STEP 2: Add webhook hook while preserving existing hooks
newWebhookHook := getstream.EventHook{
    HookType:   getstream.PtrTo("webhook"),
    Enabled:    getstream.PtrTo(true),
    EventTypes: []string{}, // empty slice = all events
    WebhookUrl: getstream.PtrTo("https://example.com/webhooks/stream/push"),
}

// STEP 3: Update with complete array including existing hooks
allHooks := append(existingHooks, newWebhookHook)
_, err = client.UpdateApp(ctx, &getstream.UpdateAppRequest{
    EventHooks: allHooks,
})
if err != nil {
    log.Fatal(err)
}

// Test the webhook connection
client.CheckPush(ctx, &getstream.CheckPushRequest{})

// 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 response = client.getApp(GetAppRequest.builder().build()).execute().getData();
var existingHooks = response.getApp().getEventHooks();
System.out.println("Current event hooks: " + existingHooks);

// STEP 2: Add webhook hook while preserving existing hooks
var newWebhookHook = EventHook.builder()
    .hookType("webhook")
    .enabled(true)
    .eventTypes(Collections.emptyList()) // empty list = all events
    .webhookUrl("https://example.com/webhooks/stream/push")
    .build();

// STEP 3: Update with complete array including existing hooks
var allHooks = new ArrayList<>(existingHooks);
allHooks.add(newWebhookHook);
client.updateApp(UpdateAppRequest.builder()
    .eventHooks(allHooks)
    .build()).execute();

// Test the webhook connection
client.checkPush(CheckPushRequest.builder()
    .build()).execute();

// 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.GetAppAsync();
var existingHooks = settings.App.EventHooks ?? new List<EventHook>();
Console.WriteLine($"Current event hooks: {existingHooks}");

// STEP 2: Add webhook hook while preserving existing hooks
var newWebhookHook = new EventHook
{
    HookType = "webhook",
    Enabled = true,
    EventTypes = new List<string>(), // empty list = all events
    WebhookUrl = "https://example.com/webhooks/stream/push",
};

// STEP 3: Update with complete array including existing hooks
var allHooks = new List<EventHook>(existingHooks) { newWebhookHook };
await client.UpdateAppAsync(new UpdateAppRequest
{
    EventHooks = allHooks,
});

// Test the webhook connection
await client.CheckPushAsync(new CheckPushRequest
{
    WebhookUrl = "https://example.com/webhooks/stream/push",
});

You can also configure specific event types by providing an array of event names instead of an empty array:

// Configure webhook for specific events only
const newWebhookHook = {
  enabled: true,
  hook_type: "webhook",
  webhook_url: "https://example.com/webhooks/stream/messages",
  event_types: ["message.new", "message.updated", "message.deleted"], // specific events
};

await client.updateAppSettings({
  event_hooks: [newWebhookHook],
});

from getstream.models import EventHook

# Configure webhook for specific events only
new_webhook_hook = EventHook(
    enabled=True,
    hook_type="webhook",
    webhook_url="https://example.com/webhooks/stream/messages",
    event_types=["message.new", "message.updated", "message.deleted"],  # specific events
)

client.update_app(event_hooks=[new_webhook_hook])

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

# Configure webhook for specific events only
new_webhook_hook = {
  'enabled' => true,
  'hook_type' => 'webhook',
  'webhook_url' => 'https://example.com/webhooks/stream/messages',
  'event_types' => ['message.new', 'message.updated', 'message.deleted'] # specific events
}

client.common.update_app(Models::UpdateAppRequest.new(
  event_hooks: [new_webhook_hook]
))

// Configure webhook for specific events only
$newWebhookHook = new Models\EventHook(
    enabled: true,
    hookType: "webhook",
    webhookUrl: "https://example.com/webhooks/stream/messages",
    eventTypes: ["message.new", "message.updated", "message.deleted"], // specific events
);

$client->updateApp(new Models\UpdateAppRequest(
    eventHooks: [$newWebhookHook],
));

// Configure webhook for specific events only
newWebhookHook := getstream.EventHook{
    HookType:   getstream.PtrTo("webhook"),
    Enabled:    getstream.PtrTo(true),
    EventTypes: []string{"message.new", "message.updated", "message.deleted"}, // specific events
    WebhookUrl: getstream.PtrTo("https://example.com/webhooks/stream/messages"),
}

client.UpdateApp(ctx, &getstream.UpdateAppRequest{
    EventHooks: []getstream.EventHook{newWebhookHook},
})

// Configure webhook for specific events only
var newWebhookHook = EventHook.builder()
    .hookType("webhook")
    .enabled(true)
    .eventTypes(List.of("message.new", "message.updated", "message.deleted")) // specific events
    .webhookUrl("https://example.com/webhooks/stream/messages")
    .build();

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

// Configure webhook for specific events only
var newWebhookHook = new EventHook
{
    HookType = "webhook",
    Enabled = true,
    EventTypes = new List<string> { "message.new", "message.updated", "message.deleted" }, // specific events
    WebhookUrl = "https://example.com/webhooks/stream/messages",
};

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

Request info

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.

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

Pending Message Options

You can configure pending message hooks to handle messages that require approval before being sent. The following options are available:

You may set up to two pending message hooks per application. Only the first commit to a pending message will succeed; any subsequent commit attempts will return an error, as the message is no longer pending. If multiple hooks specify a timeout_ms, the system will use the longest timeout value.

For more information on configuring pending messages, please refer to the Pending Messages documentation.

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.