Webhooks Overview

LAST EDIT Sep 25 2023

By using webhooks, you can tightly integrate your server application with Stream Chat. The platform supports three kinds of webhooks: Push, Before-Message-Send, and Custom Commands. All of them follow the common set of rules:

  • Webhook should be reachable from the public internet. Tunneling services like Ngrok are supported

  • Webhook should accept HTTP POST requests with JSON payload

  • Webhook should respond with response codes from 200 to 299

  • Webhook should respond as fast as possible. The exact time given for the response varies between webhook types

  • Webhook should be ready to accept the same call multiple times: in case of network or remote server failure Stream Chat could retry the request (behavior varies between webhook types)

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

Security and Performance

Copied!

We highly recommend following common security guidelines to make your webhook integration safe and fast:

  • Use HTTPS with a certificate from a trusted authority (eg. Let's Encrypt)

  • Verify the "X-Signature" header

  • Support HTTP Keep-Alive

  • Be highly available

  • Offload the processing of the message if possible (read, store, and forget)

Webhook types

Copied!

Stream Chat supports several webhook types:

Type

Description

Push

Push webhook is useful when you want your server application to receive all important events happening in the Stream Chat

Before Message Send

This webhook allows you to modify or moderate message content before sending it to the chat for everyone to see

Custom Commands

This webhook reacts to custom /slash commands

Please consult with corresponding pages to choose the webhook type that best fits your needs

Signature

Copied!

All HTTP requests can be verified as coming from Stream (and not tampered by a 3rd party) by analyzing the signature attached to the request. Every request includes an HTTP header called "X-Signature" containing a cryptographic signature of the message. Your webhook endpoint can validate that payload and signature match:

If your application uses more than one API Key, you can use the HTTP Header X-Api-Key to match the signature to the correct secret. Stream will always use the oldest key.

Configuration

Copied!

You can configure your webhook endpoints in the Stream Chat Dashboard or by using server-side SDK client:

Also, webhooks could be configured using our CLI client:

See the CLI introduction for more information on the Stream CLI.

Restricting access to webhook

Copied!

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.

US-East

ZONE ID

eip

Primary

use1-az2

34.225.10.29/32

Secondary

use1-az4

34.198.125.61/32

Tertiary

use1-az3

52.22.78.160/32

Quaternary

use1-az6

3.215.161.238/32

EU-west

ZONE ID

eip

Primary

euw1-az3

52.212.14.212/32

Secondary

euw1-az1

52.17.43.232/32

Tertiary

euw1-az2

34.241.110.177/32

Sydney

ZONE ID

eip

Primary

apse2-az3

54.252.193.245/32

Secondary

apse2-az2

13.55.254.141/32

Tertiary

apse2-az1

3.24.48.104/32

mumbai

ZONE ID

eip

Primary

aps1-az1

65.1.48.87/32

Secondary

aps1-az3

15.206.221.25/32

Tertiary

aps1-az2

13.233.48.78/32

Singapore

ZONE ID

eip

Primary

apse1-az2

13.229.11.158/32

Secondary

apse1-az1

52.74.225.150/32

Tertiary

apse1-az3

52.76.180.70/32

OHIO

ZONE ID

EIP

Primary

use2-az1

3.14.163.216/32

Secondary

use2-az2

3.15.245.3/32

Tertiary

use2-az3

3.141.116.179/32

CANADA

ZONE ID

EIP

Primary

cac1-az1

35.183.141.98/32

Secondary

cac1-az2

52.60.71.231/32

Tertiary

cac1-az4

3.97.253.35/32