Skip to content

Instantly share code, notes, and snippets.

@roerohan

roerohan/dyte_webhook_docs.md

Last active February 10, 2021 10:34
Show Gist options
  • Save roerohan/9e9c5b8b5b636cd292a3b25a734a17fc to your computer and use it in GitHub Desktop.
Save roerohan/9e9c5b8b5b636cd292a3b25a734a17fc to your computer and use it in GitHub Desktop.
Download ZIP
Documentation for webhooks by dyte.
Raw
dyte_webhook_docs.md

Webhooks by dyte

API

The API specification for webhooks is given as follows:

Note: All requests require a valid Authorization header to work as intended. All requests and responses are in JSON format.

POST /v1/organizations/{organizationId}/webhook

A POST request to /webhook can be used to register a new webhook for your organization.

Message Body

Note: The URL field must be a unique URL

{
    "name": "myWebhook1",
    "url": "https://myOrganization.com/webhook",
    "events": [
        "meeting.started",
        "meeting.ended",
        "meeting.participantJoined",
        "meeting.participantLeft",
        "recording.statusUpdate"
    ]
}

Sample Response

{
    "success": true,
    "data": {
        "webhook": {
            "id": "a3044f50-a805-457d-a237-b243d1381b1c",
            "name": "myWebhook1",
            "url": "https://myOrganization.com/webhook",
            "events": [
                "meeting.started",
                "meeting.ended",
                "meeting.participantJoined",
                "meeting.participantLeft",
                "recording.statusUpdate"
            ],
            "organizationId": "a784edbb-d96d-4fb0-98c7-8f5c8e4c6b9d"
        }
    }
}

GET /v1/organizations/{organizationId}/webhook

A GET request to /webhook can be used to get all registered webhooks for the organization.

Sample Response

{
    "success": true,
    "data": {
        "webhooks": [
            {
                "id": "a3044f50-a805-457d-a237-b243d1381b1c",
                "name": "myWebhook1",
                "url": "https://myOrganization.com/webhook",
                "events": [
                    "meeting.started",
                    "meeting.ended",
                    "meeting.participantJoined",
                    "meeting.participantLeft",
                    "recording.statusUpdate"
                ],
                "organizationId": "a784edbb-d96d-4fb0-98c7-8f5c8e4c6b9d"
            },
            {
                "id": "4ef7fb10-d76b-42fa-8158-60ae44f1cfe3",
                "name": "myWebhook2",
                "url": "https://myOrganization.com/webhook2",
                "events": [
                    "meeting.started",
                    "meeting.ended",
                    "recording.statusUpdate"
                ],
                "organizationId": "a784edbb-d96d-4fb0-98c7-8f5c8e4c6b9d"
            }
        ]
    }
}

GET /v1/organizations/{organizationId}/webhook/{webhookId}

A GET request to /webhook/{webhookId} returns the details about that webhook.

Message Body

{
    "success": true,
    "data": {
        "webhook": {
            "id": "a3044f50-a805-457d-a237-b243d1381b1c",
            "name": "myWebhook1",
            "url": "https://myOrganization.com/webhook",
            "events": [
                "meeting.started",
                "meeting.ended",
                "meeting.participantJoined",
                "meeting.participantLeft",
                "recording.statusUpdate"
            ],
            "organizationId": "a784edbb-d96d-4fb0-98c7-8f5c8e4c6b9d"
        }
    }
}

PUT /v1/organizations/{organizationId}/webhook/{webhookId}

A PUT request to /webhook/{webhookId} can be used to modify an existing webhook.

Message Body

{
    "name": "newWebhook1",
    "url": "https://myOrganization.com/newWebhook",
    "events": [
        "meeting.started",
        "meeting.ended",
        "recording.statusUpdate",
    ]
}

Sample Response

{
    "success": true,
    "data": {
        "webhook": {
            "id": "a3044f50-a805-457d-a237-b243d1381b1c",
            "name": "newWebhook1",
            "url": "https://myOrganization.com/newWebhook",
            "events": [
                "meeting.started",
                "meeting.ended",
                "recording.statusUpdate",
            ],
            "organizationId": "a784edbb-d96d-4fb0-98c7-8f5c8e4c6b9d"
        }
    }
}

DELETE /v1/organizations/{organizationId}/webhook/{webhookId}

A DELETE request to /webhook/{webhookId} can be used to delete the webhook.

Sample Response

{
    "success": true,
    "data": {
        "webhook": {
            "id": "a3044f50-a805-457d-a237-b243d1381b1c"
        }
    }
}

Errors

In general, if any API request fails, an error is sent in the following format.

{
    "success": false,
    "message": "Description of the error."
}

Webhooks

In this section, information about the kind of data returned by each webhook has been described. Each webhook request is a HTTP POST request, where the details about the webhook are sent in the message body in JSON format.

In order to simplify the structure, we first define some types which are going to be used in the API responses later.

Meeting Interface

interface Meeting {
    organizedBy: string;
    id: string;
    title: string;
    roomName: string;
    status: string;
    createdAt: string;
}

Recording Interface

interface Recording {
    recordingId: string;
    status: 'INVOKED' | 'UPLOADED' | 'ERRORED';
    downloadUrl?: string;
    downloadUrlExpiry?: string;
    errMessage?: string;
}

In the following sections, we describe each event and the kind of data that is sent along with the webhook.

meeting.started

Type of Webhook Body

interface MeetingCreated {
    event: "meeting.started";
    meeting: Meeting;
}

Sample Webhook Body

{
    "event": "meeting.started",
    "meeting": {
        "id": "cae39473-ef23-4ca2-a9e9-98f1509354f2",
        "title": null,
        "roomName": "testing-room",
        "status": "LIVE",
        "createdAt": "2021-02-09T10:07:11.675Z",
        "organizedBy": "myOrganization"
    }
}

meeting.ended

Type of Webhook Body

interface MeetingEnded {
    event: "meeting.ended";
    meeting: Meeting;
}

Sample Webhook Body

{
    "event": "meeting.ended",
    "meeting": {
        "id": "cae39473-ef23-4ca2-a9e9-98f1509354f2",
        "title": null,
        "roomName": "testing-room",
        "status": "LIVE",
        "createdAt": "2021-02-09T10:07:11.675Z",
        "organizedBy": "myOrganization"
    }
}

meeting.participantJoined

Type of Webhook Body

interface MeetingParticipantJoined {
    event: "meeting.participantJoined";
    meeting: Meeting;
    participant: {
        userDisplayName: string;
        peerId: string;
    };
}

Sample Webhook Body

{
    "event": "meeting.participantJoined",
    "meeting": {
        "id": "cae39473-ef23-4ca2-a9e9-98f1509354f2",
        "title": null,
        "roomName": "testing-room",
        "status": "LIVE",
        "createdAt": "2021-02-09T10:07:11.675Z",
        "organizedBy": "myOrganization"
    },
    "participant": {
        "userDisplayName": "Rohan",
        "peerId": "7eef23c6-1985-492b-9b95-99bac37b60d7"
    }
}

meeting.participantLeft

Type of Webhook Body

interface MeetingParticipantLeft {
    event: "meeting.participantJoined";
    meeting: Meeting;
    participant: {
        userDisplayName: string;
        peerId: string;
    };
}

Sample Webhook Body

{
    "event": "meeting.participantLeft",
    "meeting": {
        "id": "cae39473-ef23-4ca2-a9e9-98f1509354f2",
        "title": null,
        "roomName": "testing-room",
        "status": "LIVE",
        "createdAt": "2021-02-09T10:07:11.675Z",
        "organizedBy": "myOrganization"
    },
    "participant": {
        "userDisplayName": "Rohan",
        "peerId": "7eef23c6-1985-492b-9b95-99bac37b60d7"
    }
}

recording.statusUpdate

Type of Webhook Body

interface RecordingStatusUpdate {
    event: "recording.statusUpdate";
    meeting: Meeting;
    recording: Recording;
}

Sample Webhook Body

Webhook Body for recording started.

{
    "event": "recording.statusUpdate",
    "meeting": {
        "id": "cae39473-ef23-4ca2-a9e9-98f1509354f2",
        "title": null,
        "roomName": "testing-room",
        "status": "LIVE",
        "createdAt": "2021-02-09T10:07:11.675Z",
        "organizedBy": "myOrganization"
    },
    "recording": {
        "recordingId": "7a789a2d-1142-4be3-a208-4d25a75663e7",
        "status": "INVOKED"
    }
}

Webhook Body for recording uploaded.

{
    "event": "recording.statusUpdate",
    "meeting": {
        "id": "cae39473-ef23-4ca2-a9e9-98f1509354f2",
        "title": null,
        "roomName": "testing-room",
        "status": "LIVE",
        "createdAt": "2021-02-09T10:07:11.675Z",
        "organizedBy": "myOrganization"
    },
    "recording": {
        "recordingId": "7a789a2e-1141-4bd3-a908-4d30a75773e7",
        "status": "UPLOADED",
        "downloadUrl": "https://dyte-recordings.s3.ap-south-1.amazonaws.com/4086c8ec-d410-4707-a976-3021ea432afe/testing-room_1612865231994.mp4?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIA5YIELHA%2F20210209%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20210209T100821Z&X-Amz-Expires=432000&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEJL%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaCmFwLXNvdXRoLTEiSDBGAiEAuTSvvZqzO2pUqbDhARzAL3VFoyy0Y46EIzM7W%2Ff0VpcCIQC6tX%2BjoVyuZR2hBPkVoVi8Wjk2EgHjRso%2FyTieku6a7Cq%2FAwiL%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F8BEAAaDDk0NDkwODYyMTQxMCIMYaJWugiFY9VEWG%2F8KpMDm0QQG%2BaorDTJWlYrWeDMMyZv74rxS2B6VOEAMM%DtDELOD9HFdK33wLiO8AUYoIOqm1Y7cN0xKNRjE%2BLT9F1Un3iFWH6Wjv09N6y9Nd4%2rZJaVajtKuxJW710HBOK6kCscKWgMuNwy7qpm042WdjOuwkN3E%2BIW9tbELWeQrWy0XOd6pVp7vhZuaVQqB0Vq1dQ2xz6kTMAKDGbPbM6qZnY7SzWdKzNsPaXqJD0H%2B8VMb0No4MaHVcKfWml3dgo2UIs6Vnyr0nzPywSqHpkOtBtDxzRdh0ch08x0A6EqAoBSEJallDy4dZ3koRqFg0GB00fZ%2FXrdcRRCPvlmaWM3NwCvdyIdC31d03dc0TdHfjonizte7Ph4qdnI2tiu5J%2Fq441f5t8FvY2au0LnjSXsFB8kjJcli%2B8n%2FmxQF%2FqA%2F2dsfWyOZb881oCr1Wwe0Gc6CumcZu1Rv%2Bs2eAFXltkqfpB29jwLAGTC0vYmBBjrqAYlY8VkIx4mD5DR3kRMaS9Stn1s5Tt79dljeEWBFtfSzDmwnC%2FQENhHsFofiBf516mh62OVk160vDw%2FIEfPZCRT6w9rq%2BxhWo86unyaFPKbludpxeHlo0evjIf1PM9LdapoSHMSRxk6hpbwNu5oODPFEsEHxjwPfTrsrQzEgg%2BusLCK%2BVSfQsLhN8oyZvOZKvK%2FmRBh3fORICjG4UcvQ%2FVkqpjFKgdfR5NAuBlJWEWwFwxz1fJ2Ix9USb3ygAMvkcI2C6%2BHVqzRYpONYsmrum3mJcL4SOpaMTgSMwfBmYhtPuFAZH8G5rUiJKA%3D%3D&X-Amz-Signature=1df1f6b43c86e7cbfb529deed007724ebac0fa6a0d884c9fa9179881d61541f4&X-Amz-SignedHeaders=host",
        "downloadUrlExpiry": "2021-02-14T10:08:21.917Z"
    }
}

Webhook Body for recording error.

{
    "event": "recording.statusUpdate",
    "meeting": {
        "id": "cae39473-ef23-4ca2-a9e9-98f1509354f2",
        "title": null,
        "roomName": "testing-room",
        "status": "LIVE",
        "createdAt": "2021-02-09T10:07:11.675Z",
        "organizedBy": "myOrganization"
    },
    "recording": {
        "recordingId": "7a789a2e-1141-4bd3-a908-4d30a75773e7",
        "status": "ERRORED",
        "errMessage": "Description of the error."
    }
}
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment