Jitsi as a Service

Welcome to the 8x8 developer hub. You'll find comprehensive guides and documentation to help you start working with 8x8 as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started

Webhooks Reference

Jitsi as a Service Webhooks Reference

Overview

A webhook enables you to obtain notifications from the Jitsi as a Service (JaaS) platform as changes to your data occur. Information is pushed to an endpoint you define rather than pulled from an API. When an event is triggered the JaaS platform sends you a notification as an HTTP POST request, with a JSON body, to the Webhook endpoint you specify.

Webhooks can be triggered by selected and defined by events that take place during a meeting (in-meeting) or after a meeting has concluded (post-meeting) that are generated by your tenant.

Defining a Webhook endpoint

You can define a Webhook endpoint by clicking Add endpoint and specifying a mandatory target URL. After you have added the webhook, you can select one or more events that will trigger requests to the defined Webhook endpoint. The added Webhook endpoints are listed by URL and list of events.

You can optionally configure an Authorization header to be sent with each Webhook request. This enables you to authorize incoming requests.

The following screen shot shows a PARTICIPANT_JOINED action event configuration:

You can later edit the current Webhook endpoint by selecting it from the list, or add more Webhook endpoints for other significant meeting events.

The following screen shot shows the completed webhook configuration:

The Webhook endpoint expects data through a POST request and confirms successful data receipt through the return of an 2xx status code. If a successful status is not returned, follow up Webhook delivery attempts are made with an exponential back off.

The same event might occasionally be delivered more than once which guards against duplicated events using the idempotencyKey.

Event ordering is not guaranteed; therefore, PARTICIPANT_JOINED might be received prior to ROOM_CREATED.

Events

The following list describes some of the possible webhook eventTypes (enums):

  • ROOM_CREATED: the first participant joins a room
  • PARTICIPANT_LEFT: a participant leaves the meeting
  • TRANSCRIPTION_UPLOADED: a meeting transcription is uploaded
  • CHAT_UPLOADED: the meeting chat is successfully uploaded
  • ROOM_DESTROYED: the meeting room is destroyed after all of the participants have left
  • PARTICIPANT_JOINED: a new participant joins an ongoing meeting
  • RECORDING_UPLOADED: the meeting recording is uploaded
  • LIVE_STREAM_STARTED: live streaming started
  • LIVE_STREAM_ENDED: live streaming ended
  • SETTINGS_PROVISIONING: allow customers the option to define pre-meeting password and lobby settings

Payload structure

The JaaS webhook requests have the following payload structure types:

  • idempotencyKey (string): The GUID value identifying the request. Two requests having the same idempotencyKey are duplicated, thus the latter needs to be ignored. JaaS recommends using an internal map in order to keep track of duplicate requests.
  • customerId (string): The ID of the current JaaS implementation user
  • eventType (enum: one of eventTypes): The current request type as described in the eventTypes section.
  • sessionId (string): The identifier for the current meeting session.
  • timestamp (long): The unique Unix timestamp for the event. Since events are not guaranteed to be cataloged in chronological order on the listening Webhook endpoint, consider this notation as the source of truth.
  • fqn (string): The fully qualified name (fqn) of the meeting in the format [tenant]/[room name]
  • data (object): This object contains data specific to each of the noted eventTypes.

The following shows the object structure per event type:

  • ROOM_CREATED:

    • conference (string): The full room name.

      For example:

      {
          "idempotencyKey": "d11f155d-ced5-4a7e-b6d9-aaa135c64f65",
          "customerId": "c2824d584eac4489a1e32e4e164d5a3c",
          "eventType": "ROOM_CREATED",
          "sessionId": "c3348153-1027-4382-afad-5ae91b433c26",
          "timestamp": 1600951800112,
          "fqn": "vpaas-magic-cookie-c2824d584eac4489a1e32e4e164d5a3c/testroom2",
          "data": {
              "conference": "[email protected]164d5a3c.stage.8x8.vc"
          }
      }
      
      
  • PARTICIPANT_LEFT:

    • moderator (boolean or string: “true”|”false”`): Identifies whether the participant is a moderator for the meeting

    • name (string): The full name of the participant

    • group (string): The participant's group affiliation

    • email (string): The participant’s email

    • id (string): The participant’s userId

    • participantJid (string): The participant’s xmpp (prosody) jid (jabber id)

    • avatar (string): The participant’s avatar URL.

      For example:

      {
          "idempotencyKey": "0de492ee-1efa-4a50-8b41-66904e12e282",
          "customerId": "c2824d584eac4489a1e32e4e164d5a3c",
          "eventType": "PARTICIPANT_LEFT",
          "sessionId": "c3348153-1027-4382-afad-5ae91b433c26",
          "timestamp": 1600952723655,
          "fqn": "vpaas-magic-cookie-c2824d584eac4489a1e32e4e164d5a3c/testroom2",
          "data": {
              "moderator": "true",
              "name": "John Doe",
              "group": "vpaas-magic-cookie-c2824d584eac4489a1e32e4e164d5a3c",
              "email": "[email protected]",
              "id": "uniqueUserIdentifier",
              "participantJid": "[email protected]",
              "avatar": "https://link.to/user/avatar/picture"
           }
      }
      
  • TRANSCRIPTION_UPLOADED:

  • CHAT_UPLOADED: not implemented

    The webhook is called when the meeting ends.

    • preAuthenticatedLink (string): The preauthenticated download URL for the meeting transcriptions file. The URL link is valid for 24 hours.

      For example:

      {
        "idempotencyKey": "e9536d20-41e3-4944-9c37-46b786abf793",
        "customerId": "c2824d584eac4489a1e32e4e164d5a3c",
        "eventType": "TRANSCRIPTION_UPLOADED",
        "sessionId": "38e68a1f-8975-4518-99df-5f151eaf31e3",
        "timestamp": 1612352845815,
        "fqn": "vpaas-magic-cookie-c2824d584eac4489a1e32e4e164d5a3c/testroom",
        "data": {
          "preAuthenticatedLink": "https://link.to/transcriptions/file"
        }
      }
      
  • CHAT_UPLOADED:
    The webhook is called when the meeting ends.

    • preAuthenticatedLink (string): The preauthenticated download URL for the meeting chat file. The URL link is valid for 24 hours.
      For example:
      {
        "idempotencyKey": "e9536d20-41e3-4944-9c37-46b786abf793",
        "customerId": "c2824d584eac4489a1e32e4e164d5a3c",
        "eventType": "CHAT_UPLOADED",
        "sessionId": "38e68a1f-8975-4518-99df-5f151eaf31e3",
        "timestamp": 1612352845815,
        "fqn": "vpaas-magic-cookie-c2824d584eac4489a1e32e4e164d5a3c/testroom",
        "data": {
          "preAuthenticatedLink": "https://link.to/chat/file"
        }
      }
      
  • ROOM_DESTROYED:

    • conference (string): The full room name

      For example:

      {
          "idempotencyKey": "251d4ca8-6192-403c-9098-645042679257",
          "customerId": "c2824d584eac4489a1e32e4e164d5a3c",
          "eventType": "ROOM_DESTROYED",
          "sessionId": "c3348153-1027-4382-afad-5ae91b433c26",
          "timestamp": 1600952155289,
          "fqn": "vpaas-magic-cookie-c2824d584eac4489a1e32e4e164d5a3c/testroom2",
          "data": {
              "conference": "[email protected]164d5a3c.stage.8x8.vc"
          }
      }
      
  • PARTICIPANT_JOINED:

    • moderator (boolean or string: “true”|”false”`): Identifies whether the participant is a moderator for the meeting

    • name (string): The full name of the participant

    • group (string): The participant’s group name

    • email (string): The participant’s email of the participant

    • id (string): The participant’s userId

    • participantJid (string): The participant’s xmpp (prosody) jid (jabber id)

    • avatar (string): The participant’s avatar URL

      For example:

      {
          "idempotencyKey": "45892714-7bf6-49b8-8c6a-856a92ff6d8a",
          "customerId": "c2824d584eac4489a1e32e4e164d5a3c",
          "eventType": "PARTICIPANT_JOINED",
          "sessionId": "c3348153-1027-4382-afad-5ae91b433c26",
          "timestamp": 1600951818143,
          "fqn": "vpaas-magic-cookie-c2824d584eac4489a1e32e4e164d5a3c/testroom2",
          "data": {
              "moderator": "true",
              "name": "John Doe",
              "group": "vpaas-magic-cookie-c2824d584eac4489a1e32e4e164d5a3c",
              "email": "[email protected]",
              "id": "uniqueUserIdentifier",
              "participantJid": "[email protected]",
              "avatar": "https://link.to/user/avatar/picture"
           }
      }
      
  • RECORDING_UPLOADED:

    • participants (an array of objects): The list of participants in a meeting when recording was uploaded.

    • name (string): The full name of the user

    • avatar (string): The user’s avatar URL

    • id (string): The userId

    • preAuthenticatedLink (string): The preauthenticated download URL for the meeting recording. The URL link is valid for 24 hours.

    • share (boolean): Identifies whether the recording is shared

    • initiatorId (string): The id of the recording initiator

    • durationSec (long): The duration of the recording in seconds

    • startTimestamp (long): The UNIX timestamp in milliseconds when the recording has started

    • endTimestamp (long): The UNIX timestamp in milliseconds when the recording has ended

      For example:

      {
          "idempotencyKey": "c2b42ad3d-12a6-5908-cf38-f21ae2451fc0",
          "customerId": "c2824d584eac4489a1e32e4e164d5a3c",
          "eventType": "RECORDING_UPLOADED",
          "sessionId": "c3348153-1027-4382-afad-5ae91b433c26",
          "timestamp": 1600952817465,
          "fqn": "vpaas-magic-cookie-c2824d584eac4489a1e32e4e164d5a3c/testroom2",
          "data": {
              "participants": [
                  {
                      "user": {
                          "name": "John Doe",
                          "avatar": "https://link.to/user/avatar/picture1",
                          "id": "uniqueUserIdentifier1"
                      }
                  },
                  {
                      "user": {
                          "name": "John Doe2",
                          "avatar": "https://link.to/user/avatar/picture2",
                          "id": "uniqueUserIdentifier2"
                      }
                  }
               ],
              "preAuthenticatedLink": "https://objectstorage.us-phoenix-1.oraclecloud.com/p/hrnGsHYw-ct5undQ5eL3zK1r1UzqHlnYMwRtCdDgn22qx7GZTOl_NDL5ACC4UbJk/n/fr4eeztjonbe/b/vpaas-recordings-stage-8x8-us-phoenix-1/o/vpaas-magic-cookie-c2824d584eac4489a1e32e4e164d5a3c/testroom2_2020-09-24-12-01-07.mp4",
              "share": true,
              "initiatorId": "uniqueUserIdentifier1",
              "durationSec": 15,
              "startTimestamp": 1612175247396,
              "endTimestamp": 1612175263000
            }
      }
      
  • LIVE_STREAM_STARTED:

    • conference (string): The full room name

      For example:

      {
        "idempotencyKey": "251d4ca8-6192-403c-9098-645042679257",
        "customerId": "c2824d584eac4489a1e32e4e164d5a3c",
        "eventType": "LIVE_STREAM_STARTED",
        "sessionId": "c3348153-1027-4382-afad-5ae91b433c26",
        "timestamp": 1612354430008,
        "fqn": "vpaas-magic-cookie-c2824d584eac4489a1e32e4e164d5a3c/testroom2",
        "data": {
          "conference": "[email protected]164d5a3c.stage.8x8.vc"
        }
      }
      
  • LIVE_STREAM_ENDED:

    • conference (string): The full room name

      For example:

      {
        "idempotencyKey": "251d4ca8-6192-403c-9098-645042679257",
        "customerId": "c2824d584eac4489a1e32e4e164d5a3c",
        "eventType": "LIVE_STREAM_ENDED",
        "sessionId": "c3348153-1027-4382-afad-5ae91b433c26",
        "timestamp": 1612354445154,
        "fqn": "vpaas-magic-cookie-c2824d584eac4489a1e32e4e164d5a3c/testroom2",
        "data": {
          "conference": "[email protected]164d5a3c.stage.8x8.vc"
        }
      }
      
  • SETTINGS_PROVISIONING:

    • Before every meeting the registered URL will be called using a POST request with payload:
      {
        "fqn": "tenant/roomName"
      }
      
    • The expected json response from the registered URL:
      {
        "lobbyEnabled": true,
        "passcode": "0000"
      }
      
    • lobbyEnabled (boolean: true|false): If the value is true the meeting will start with lobby enabled and only moderators can join, participants will wait in the lobby until a moderator give them access. If false or the field is missing from the response the meeting will start without a lobby.
    • passcode (string: digits only): The passcode that the meeting will start with. If empty or the field is missing the meeting will start without a passcode.

Updated 5 days ago


Webhooks Reference


Jitsi as a Service Webhooks Reference

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.