A Webhook is a mechanism for Streem's customers to get notified of events that happen on our backend.

  • Customers are able to configure multiple webhook endpoints
  • Customers are able to specify the method and headers that should be sent with the webhook
  • Retry and backoff are implemented, to give customer servers a better chance to successfully process messages
  • Requests include an ID so that customer server can de-dupe requests, if needed
  • Requests are signed so that the customer server can validate that the request was sent by Streem


  • Create a webhook: POST /v1/webhooks.

    • Example code from the Click To Video Example app:

      • import axios, { AxiosRequestConfig } from 'axios';
        import { streemConfig } from '../../env';
        export default class StreemApi {
            private readonly baseUrl: string;
            private readonly config: Partial<AxiosRequestConfig>;
            static instance(): StreemApi {
                return new StreemApi(
                    `Basic ${Buffer.from(`${streemConfig.apiKeyId}:${streemConfig.apiKeySecret}`).toString('base64')}`
            private constructor(apiEnv: string, authHeader: string) {
                this.baseUrl = `https://api.${apiEnv}`;
                this.config = {
                    headers: {
                        Authorization: authHeader,
                        'Content-Type': 'application/json',
                        Accept: 'application/json',
            async createWebhook(
                companySid: string,
                webhookUrl: string,
                label: string,
                method: string,
            ): Promise<Webhook> {
                const url = `${this.baseUrl}/v1/webhooks`;
                const res = await<{ webhook: Webhook }>(
                        company_sid: companySid,
                        label: label,
                        url: webhookUrl,
                        method: method,
                        timeout_ms: 5000,
                        max_attempts: 5,
                        "headers": [
                                "name": "X-Streem-API-Key-ID",
                                "value": streemConfig.apiKeyId,
                                "include_in_request_signature": true
                    { ...this.config },
  • Streem will automatically create a default signing key for a new webhook. But you can define your own signing key through: POST /v1/webhooks/{webhook_sid}/signing-keys

  • Test a webhook: GET /v1/webhooks/{webhook_sid}/~test

  • Retrieve a webhook: GET /v1/webhooks/{webhook_sid}

  • List all webhooks: GET /v1/webhooks?page_size=10&sort=url.asc&company_sid={company_sid}

  • Retrieve a signing key: GET /v1/webhooks/{webhook_sid}/signing-keys/{signing_key_sid}

  • List all signing keys: GET /v1/webhooks/{{webhook_sid}}/signing-keys?page_size=10&sort=label.asc