Webhooks Overview

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:

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)

Stream Chat supports several webhook types:

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:

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:

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.