Multi-Event Hooks

Overview

Stream now supports configuring multiple webhook endpoints for different event types, giving you more flexibility in handling various events. This feature allows you to route different types of events to different endpoints, making your webhook architecture more organized and efficient.

Migration

If you only see a single webhook URL in your dashboard, your application hasn’t been migrated to the new multi-event hooks system yet. We are currently in the process of gradually rolling out this feature across all Stream applications. Once your app is migrated, you’ll have access to the multi-event hooks configuration described in this section.

Configuration

You can configure multi-event hooks through the Stream Dashboard or using the server-side SDKs.

Using the Dashboard

  1. Go to the Stream Dashboard
  2. Select your app
  3. Navigate to your app’s settings until “Webhook & Event Configuration” section
  4. Add and configure webhook, SQS, SNS, and pending message

Using Server-Side SDKs

Event hooks are managed using the Update App Settings method, which performs upsert and delete operations:

  • Create: New hooks are created if the ID doesn’t exist in our database
  • Update: Existing hooks are updated if the ID matches in our database
  • Delete: Hooks not included in the request are automatically deleted

You can provide the ID or not. If you don’t provide the ID, the system will generate a new random UUID everytime you update the hook. It’s up to your convenience.

Here’s how to configure event hooks using our server SDKs:

// Get current app settings
const response = await client.getAppSettings();
console.log("Current event hooks:", response.event_hooks);

// The updateAppSettings method performs upsert and delete operations:
// - Creates new hooks if ID doesn't exist in our database
// - Updates existing hooks if ID matches in our database
// - Deletes hooks that are excluded from the list

// Example 1: Create new event hooks (assuming no existing hooks)
await client.updateAppSettings({
  event_hooks: [
    {
      id: "{generate random uuid}", // New webhook hook
      enabled: true,
      hook_type: "webhook",
      webhook_url: "https://example.com/webhook",
      event_types: ["message.new", "message.updated"],
    },
    {
      // You can also create a new hook without providing the ID, the system will generate it
      enabled: true,
      hook_type: "sqs", // New SQS hook
      sqs_queue_url:
        "https://sqs.us-east-1.amazonaws.com/123456789012/queue-name",
      sqs_region: "us-east-1",
      sqs_auth_type: "resource",
      event_types: ["user.updated"],
    },
  ],
});

// Example 2: Update existing webhook, add a second webhook, add SNS and pending message
await client.updateAppSettings({
  event_hooks: [
    {
      // Update existing webhook
      id: "{id from creation}", // you can provide the ID or not. If you don't provide the ID, the system will generate a new random UUID every time you update the hook. It's up to your convenience.
      enabled: true,
      hook_type: "webhook",
      webhook_url: "https://updated-webhook-url.com", // Changed URL
      event_types: ["message.new", "message.updated", "message.deleted"], // Added event type
    },
    {
      id: "{id from creation}", // Keep existing SQS hook unchanged
      enabled: true,
      hook_type: "sqs",
      sqs_queue_url:
        "https://sqs.us-east-1.amazonaws.com/123456789012/queue-name",
      sqs_region: "us-east-1",
      sqs_auth_type: "resource",
      event_types: ["user.updated"],
    },
    {
      // Add second webhook
      enabled: true,
      hook_type: "webhook",
      webhook_url: "https://secondary-webhook-url.com",
      event_types: [], // for all existing and future event types
    },
    {
      // Add new SNS hook
      enabled: true,
      hook_type: "sns",
      sns_topic_arn: "arn:aws:sns:us-east-1:123456789012:topic-name",
      sns_region: "us-east-1",
      sns_auth_type: "resource",
      event_types: ["channel.updated"],
    },
    {
      // Add new pending message hook
      enabled: true,
      hook_type: "pending_message",
      webhook_url: "http://test-url.com",
      timeout_ms: 500,
      callback: {
        mode: "CALLBACK_MODE_REST",
      },
    },
  ],
  // Note: Any previously existing hooks not included here will be deleted
});

// Example 3: Delete specific hooks by excluding them
await client.updateAppSettings({
  event_hooks: [
    {
      id: "{id from creation}", // Keep only webhook hook
      enabled: true,
      hook_type: "webhook",
      webhook_url: "https://example.com/webhook",
      event_types: ["message.new", "message.updated"],
    },
    // SQS, SNS, and pending message hooks will be deleted because they're not included
  ],
});

// Example 4: Delete all event hooks
await client.updateAppSettings({
  event_hooks: [], // Empty array deletes all existing hooks
});

Configuration Options

Each event hook configuration supports different options based on its type:

Common Options

OptionTypeDescriptionRequired
idstringUnique identifier for the event hookYes for updating hooks. If empty, it will generate an ID.
enabledbooleanBoolean flag to enable/disable the hookYes
hook_typestringType of hook (“webhook”, “sqs”, “sns”, “pending_message”)Yes
productstringConfigure hook for a specific product (“all”, “chat”, “video”, “moderation”, “feeds”)No. Default is “all”.
event_typesarrayArray of event types this hook should handleNo. Not provided or empty array means subscribe to all existing and future events.

Webhook Options

OptionTypeDescriptionRequired
webhook_urlstringThe URL where events will be sent. You can use URL templating to handle events. Example: http://my.webhook.host/{{.AppID}}/{{.EventType}}Yes

For more information on configuring webhook server, please refer to the Webhooks Overview documentation.

SQS Options

OptionTypeDescriptionRequired
sqs_queue_urlstringThe AWS SQS queue URLYes
sqs_auth_typestringAuthentication type (“keys”, “role”, or “resource”)Yes
sqs_keystringAWS access key ID (if auth_type is “keys”)Yes if using key auth
sqs_secretstringAWS secret access key (if auth_type is “keys”)Yes if using key auth
sqs_role_arnstringAWS IAM role ARN (if auth_type is “role”)Yes if using role auth

For more information on configuring SQS server, please refer to the SQS documentation.

SNS Options

OptionTypeDescriptionRequired
sns_topic_arnstringThe AWS SNS topic ARNYes
sns_auth_typestringAuthentication type (“keys”, “role”, or “resource”)Yes
sns_keystringAWS access key ID (if auth_type is “keys”)Yes if using key auth
sns_secretstringAWS secret access key (if auth_type is “keys”)Yes if using key auth
sns_role_arnstringAWS IAM role ARN (if auth_type is “role”)Yes if using role auth

For more information on configuring SNS server, please refer to the SNS documentation.

Pending Message Options

OptionTypeDescriptionRequired
webhook_urlstringThe URL where pending message events will be sentYes, except for CALLBACK_MODE_NONE
timeout_msnumberTimeout in millisecondsYes
callback.modestringCallback mode (“CALLBACK_MODE_NONE”, “CALLBACK_MODE_REST”, “CALLBACK_MODE_TWIRP”)Yes

You can configure up to two pending message hooks. Only the first commit will take effect. The second commit will return an error because the message is no longer pending.

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

© Getstream.io, Inc. All Rights Reserved.