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 you are maintaining a whitelist of servers allowed to connect to your app, you will need to add Stream's servers to that whitelist for Webhooks to work.