Webhooks Overview

Confused about "Webhooks Overview"?

Let us know how we can improve our documentation:

Send

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:

Security and PerformanceCopied!

Confused about "Security and Performance"?

Let us know how we can improve our documentation:

Send

We highly recommend following common security guidelines to make you webhook integration safe and blazing 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 typesCopied!

Confused about "Webhook types"?

Let us know how we can improve our documentation:

Send

Stream Chat supports several webhook types:

SignatureCopied!

Confused about "Signature"?

Let us know how we can improve our documentation:

Send

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:

1
2
// first argument is the request body as a string, second the signature header 
const valid = client.verifyWebhook(req.rawBody, req.headers['x-signature']);

1
2
3
4
5
6
7
8
9
import stream_chat 
 
client = StreamChat(api_key="STREAM_KEY", api_secret="STREAM_SECRET") 
 
# Django request 
valid = client.verify_webhook(request.body, request.META['HTTP_X_SIGNATURE']) 
 
# Flask request 
valid = client.verify_webhook(request.data, request.headers['X-SIGNATURE'])

1
2
3
4
5
6
require 'stream-chat' 
 
client = StreamChat::Client.new(api_key='STREAM_KEY', api_secret='STREAM_SECRET') 
 
// signature comes from the HTTP header x-signature 
valid = client.verify_webhook(request_body, signature)

1
2
3
4
$client = new GetStream\StreamChat\Client("STREAM_API_KEY", "STREAM_API_SECRET"); 
 
// signature comes from the HTTP header x-signature 
$valid = $client->verifyWebhook($requestBody, $signature);

1
2
3
4
client, _ := stream.NewClient(APIKey, []byte(APISecret)) 
 
// signature comes from the HTTP header x-signature 
isValid := client.VerifyWebhook(body, signature)

1
2
3
4
5
6
using StreamChat; 
 
var client = new Client("API KEY", "API SECRET"); 
 
// signature comes from the HTTP header x-signature  
client.VerifyWebhook(requestBody, signature);

ConfigurationCopied!

Confused about "Configuration"?

Let us know how we can improve our documentation:

Send

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

1
2
3
4
5
6
// update webhook URLs 
await client.updateAppSettings({ 
  webhook_url: "https://example.com/webhooks/stream/push", // sets Push webhook address 
  before_message_send_hook_url: "https://example.com/webhooks/stream/before-message-send", // sets Before Message Send webhook address 
  custom_action_handler_url: "https://example.com/webhooks/stream/custom-commands?type={type}", // sets Custom Commands webhook address 
});

Also, webhooks could be configured using our CLI client:

1
2
3
stream chat:webhook:push --url 'https://example.com/webhooks/stream/push' 
stream chat:webhook:before-message-send --url 'https://example.com/webhooks/stream/before-message-send' 
stream chat:webhook:custom-commands --url 'https://example.com/webhooks/stream/custom-commands?type={type}'