Managing

Introduction

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

APIs

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(
            streemConfig.apiEnv,
            `Basic ${Buffer.from(`${streemConfig.apiKeyId}:${streemConfig.apiKeySecret}`).toString('base64')}`
        );
    }

    private constructor(apiEnv: string, authHeader: string) {
        this.baseUrl = `https://api.${apiEnv}.streem.cloud`;
        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 axios.post<{ webhook: Webhook }>(
            url,
            {
                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 },
        );

        return res.data.webhook;
    }
}

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