Overview

Custom events

You can send custom events to all users watching a call, events can be send client-side or server-side. It is not necessary for users to be part the call, you call objects can be "watched" before joining as well. Client-side you can observe calls and receive events by passing the watch:true parameter to any of these endpoints: GetCall, QueryCalls, JoinCall.

JavaScript

// send a custom event to all users watching the call
call.sendCallEvent({
  custom: {
    'render-animation': 'balloons',
  },
  user_id: 'john',
});

Python

# send a custom event to all users watching the call
call.send_call_event(user_id=user.id, custom={"render-animation": "balloons"})

cURL

curl -X POST https://video.stream-io-api.com/api/v2/video/call/${CALL_TYPE}/${CALL_ID}/event?api_key=${API_KEY} \
  -H "Authorization: ${TOKEN}" \
  -H "stream-auth-type: jwt" \
  -H 'Content-Type: application/json' \
  -d '{
    "custom": {"render-animation": "balloons"},
    "user_id": "john"
  }'

JavaScript@0.3 (deprecated)

// send a custom event to all users watching the call
call.sendCustomEvent({
  custom: {
    'render-animation': 'balloons',
  },
  user_id: 'john',
});

You can configure your Stream app to send events to your HTTP/webhook and/or to your AWS SQS queue. Webhooks are usually the simplest way to receive events from your app and to perform additional action based on what happens to your application.

Both SQS and Webhook can be configured from the Stream Dashboard.

How to implement a webhook handler

Your webhook handler needs to follow these rules:

• accept HTTP POST requests with JSON payload
• be reachable from the public internet. Tunneling services like Ngrok are supported
• respond with response codes from 200 to 299 as fast as possible

Your webhook handler can use the type field to handle events based correctly based on their type and payload.

All webhook requests contain these headers:

Name	Description
X-WEBHOOK-ID	Unique ID of the webhook call. This value is consistent between retries and could be used to deduplicate retry calls
X-WEBHOOK-ATTEMPT	Number of webhook request attempt starting from 1
X-API-KEY	Your application’s API key. Should be used to validate request signature
X-SIGNATURE	HMAC signature of the request body. See Signature section

Security and Performance

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

• Use HTTPS with a certificate from a trusted authority
• Verify the "X-Signature" header
• Support HTTP Keep-Alive
• Be highly available
• Offload the processing of the message if possible (read, store, and forget)

Error Handling

In case of the request failure Stream Chat attempts to retry a request. The amount of maximum attempts depends on the kind of the error it receives:

• Response code is 408, 429 or >=500: 3 attempts
• Network error: 2 attempts
• Request timeout: 3 attempts

The timeout of one request is 6 seconds, and the request with all retries cannot exceed the duration of 15 seconds.