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.

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

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

// Get app settings
await client.getAppSettings();

// Response
{
  // ... all existing app settings
  "event_hooks": [
    {
      "id": "d2ce8c4f-bf5f-40b7-aeda-d2aef381fb54",
      "enabled": true,
      "hook_type": "webhook",
      "webhook_url": "http://url1-webhook.com",
      "event_types": ["channel.created"]
    },
    {
      "id": "e9b2c15b-53bd-4998-9791-491bb6742e23",
      "enabled": true,
      "hook_type": "sqs",
      "sqs_queue_url": "http://url1-sqs.com",
      "sqs_auth_type": "keys",
      "sqs_key": "sqs-key",
      "sqs_secret": "sqs-secret",
      "event_types": ["channel.created"]
    },
    {
      "id": "e9b2c15b-53bd-4998-9791-adiqeq13mqw",
      "enabled": true,
      "hook_type": "sns",
      "sns_arn_topic": "arn:aws:sns:us-east-1:123456789012:MyTopic2",
      "sns_auth_type": "role",
      "sns_role_arn": "arn:aws:iam::123456789012:role/SNSPublishRole",
      "event_types": ["channel.created", "channel.updated"]
    },
    {
      "enabled": true,
      "hook_type": "pending_message",
      "webhook_url": "http://test-url.com",
      "timeout_ms": 500,
      "callback": {
        "mode": "CALLBACK_MODE_REST"
      }
    }
  ]
}

// Update app settings
await client.updateAppSettings({
  event_hooks: [
    {
      "id": "d2ce8c4f-bf5f-40b7-aeda-d2aef381fb54",
      "enabled": true,
      "hook_type": "webhook",
      "webhook_url": "http://url1-new-webhook.com", // change the URL
      "event_types": ["channel.created", "message.new"] // add a new event type
    },
    {
      "id": "e9b2c15b-53bd-4998-9791-491bb6742e23",
      "enabled": false, // disable a hook
      "hook_type": "sqs",
      "sqs_queue_url": "http://url1-sqs.com",
      "sqs_auth_type": "keys",
      "sqs_key": "sqs-key",
      "sqs_secret": "sqs-secret",
      "event_types": ["channel.created"]
    }
    // remove e9b2c15b-53bd-4998-9791-adiqeq13mqw from the update app settings request will delete it from DB
  ]
});

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

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

Migration

If you only see a single webhook URL in your app settings, 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.

Previous
Debugging with Ngrok
Next
SQS
© Getstream.io, Inc. All Rights Reserved.