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 [AppID]/[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

The webhook is called when a conference is created.

  • conference (string): The full room name.

For example:

{
    "idempotencyKey": "d11f155d-ced5-4a7e-b6d9-aaa135c64f65",
    "customerId": "c2824d584eac4489a1e32e4e164d5a3c",
    "appId": "vpaas-magic-cookie-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:

The webhook is called when a participant left the meeting.

  • 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",
    "appId": "vpaas-magic-cookie-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:

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",
  "appId": "vpaas-magic-cookie-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",
  "appId": "vpaas-magic-cookie-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:

The webhook is called when the room is destroyed.

  • conference (string): The full room name.

For example:

{
    "idempotencyKey": "251d4ca8-6192-403c-9098-645042679257",
    "customerId": "c2824d584eac4489a1e32e4e164d5a3c",
    "appId": "vpaas-magic-cookie-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:


The webhook is called when a participant joined the meeting.

  • 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",
    "appId": "vpaas-magic-cookie-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_STARTED:

The webhook is called when recording is started.

  • conference (string): The full room name

For example:

{
   "idempotencyKey":"2a2ad143-fb2b-409e-995d-9e2fd74b8792",
   "customerId":"143ce1379c35426aa80a902a0204ed09",
   "appId": "vpaas-magic-cookie-143ce1379c35426aa80a902a0204ed09",
   "eventType":"RECORDING_STARTED",
   "sessionId":"be4d177c-a342-41e6-a9b9-8be7ff0b0cc8",
   "timestamp":1623751315624,
   "appId":"vpaas-magic-cookie-c2824d584eac4489a1e32e4e164d5a3c",
   "fqn":"vpaas-magic-cookie-c2824d584eac4489a1e32e4e164d5a3c/testroom2",
   "data":{
      "conference":"[email protected]164d5a3c.stage.8x8.vc"
   }
}

RECORDING_ENDED:

The webhook is called when recording is ended.

  • conference (string): The full room name

For example:

{
   "idempotencyKey":"12e2181c-c5b1-4421-9d6c-5d9784a0fc9b",
   "customerId":"143ce1379c35426aa80a902a0204ed09",
   "appId": "vpaas-magic-cookie-143ce1379c35426aa80a902a0204ed09",
   "eventType":"RECORDING_ENDED",
   "sessionId":"be4d177c-a342-41e6-a9b9-8be7ff0b0cc8",
   "timestamp":1623751329561,
   "appId":"vpaas-magic-cookie-c2824d584eac4489a1e32e4e164d5a3c",
   "fqn":"vpaas-magic-cookie-c2824d584eac4489a1e32e4e164d5a3c/testroom2",
   "data":{
      "conference":"[email protected]164d5a3c.stage.8x8.vc"
   }
}

RECORDING_UPLOADED:

The webhook is called when the meeting ends.

  • 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",
    "appId": "vpaas-magic-cookie-c2824d584eac4489a1e32e4e164d5a3c",
    "eventType": "RECORDING_UPLOADED",
    "sessionId": "c3348153-1027-4382-afad-5ae91b433c26",
    "timestamp": 1600952817465,
    "fqn": "vpaas-magic-cookie-c2824d584eac4489a1e32e4e164d5a3c/testroom2",
    "data": {
        "participants": [
            {
                "name": "Jane Doe",
                "avatar": "https://link.to/user/avatar/picture1",
                "id": "uniqueUserIdentifier1"
            },
            {
                "name": "John Doe ",
                "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:

The webhook is called when a live stream is started.

  • conference (string): The full room name

For example:

{
  "idempotencyKey": "251d4ca8-6192-403c-9098-645042679257",
  "customerId": "c2824d584eac4489a1e32e4e164d5a3c",
  "appId": "vpaas-magic-cookie-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:

The webhook is called when a live stream has 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": "AppID/roomName"
}
  • The expected json response from the registered URL:
{
  "lobbyEnabled": true,
  "passcode": "0000",
  "lobbyType": "WAIT_FOR_APPROVAL",
  "maxOccupants": 4
}
  • 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.
  • lobbyType (string (optional): WAIT_FOR_APPROVAL | WAIT_FOR_MODERATOR): if WAIT_FOR_MODERATOR is returned the lobby is automatically disabled after the first moderator joins. If WAIT_FOR_APPROVAL is returned or the lobbyType field is missing, non-moderator participants must ask to join and be approved by a moderator from the room.
  • maxOccupants (integer (optional)): The maximum number of participants that can be at the same time in a meeting. Should be a value between 2 and 500.

SIP_CALL_IN_STARTED:

The webhook is called when a sip call-in is started.

  • sipAddress (string): The sip address of the caller
  • participantJid (string): The participant’s xmpp (prosody) jid (jabber id)
  • nick (string): The name of the caller. Normally it's a human-readable version of the caller id

For example:

{
  "idempotencyKey": "6f36a817-a220-471f-bd51-f0fdb53e09c9",
  "customerId": "9708f84c111b4c54a8e0374fa4bcb15a",
  "appId": "vpaas-magic-cookie-9708f84c111b4c54a8e0374fa4bcb15a",
  "eventType": "SIP_CALL_IN_STARTED",
  "sessionId": "98e91f3d-0de7-4a17-b4ce-cd8fbe497d3e",
  "timestamp": 1621857054828,
  "fqn": "vpaas-magic-cookie-9708f84c111b4c54a8e0374fa4bcb15a/sampleappshyadviceprograminside",
  "data": {
    "sipAddress": "sip:[email protected]",
    "participantJid": "[email protected]",
    "nick": "nickname"
  }
}

SIP_CALL_IN_ENDED:

The webhook is called when a sip call-in is ended.

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

For example:

{
  "idempotencyKey": "6f36a817-a220-471f-bd51-f0fdb53e09c9",
  "customerId": "9708f84c111b4c54a8e0374fa4bcb15a",
  "appId": "vpaas-magic-cookie-9708f84c111b4c54a8e0374fa4bcb15a",
  "eventType": "SIP_CALL_IN_ENDED",
  "sessionId": "98e91f3d-0de7-4a17-b4ce-cd8fbe497d3e",
  "timestamp": 1621857054828,
  "fqn": "vpaas-magic-cookie-9708f84c111b4c54a8e0374fa4bcb15a/sampleappshyadviceprograminside",
  "data": {
    "participantJid": "[email protected]"
  }
}

SIP_CALL_OUT_STARTED:

The webhook is called when a sip call-out is started.

  • sipAddress (string): The sip address of the callee
  • participantJid (string): The participant’s xmpp (prosody) jid (jabber id)
  • nick (string): The name of the callee. Normally it's the sip address's username

For example:

{
  "idempotencyKey": "6f36a817-a220-471f-bd51-f0fdb53e09c9",
  "customerId": "9708f84c111b4c54a8e0374fa4bcb15a",
  "appId": "vpaas-magic-cookie-9708f84c111b4c54a8e0374fa4bcb15a",
  "eventType": "SIP_CALL_OUT_STARTED",
  "sessionId": "98e91f3d-0de7-4a17-b4ce-cd8fbe497d3e",
  "timestamp": 1621857054828,
  "fqn": "vpaas-magic-cookie-9708f84c111b4c54a8e0374fa4bcb15a/sampleappshyadviceprograminside",
  "data": {
    "sipAddress": "sip:[email protected]",
    "participantJid": "[email protected]",
    "nick": "nickname"
  }
}

SIP_CALL_OUT_ENDED:

The webhook is called when a sip call-out is ended.

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

For example:

{
  "idempotencyKey": "6f36a817-a220-471f-bd51-f0fdb53e09c9",
  "customerId": "9708f84c111b4c54a8e0374fa4bcb15a",
  "appId": "vpaas-magic-cookie-9708f84c111b4c54a8e0374fa4bcb15a",
  "eventType": "SIP_CALL_OUT_ENDED",
  "sessionId": "98e91f3d-0de7-4a17-b4ce-cd8fbe497d3e",
  "timestamp": 1621857054828,
  "fqn": "vpaas-magic-cookie-9708f84c111b4c54a8e0374fa4bcb15a/sampleappshyadviceprograminside",
  "data": {
    "participantJid": "[email protected]"
  }
}

FEEDBACK:

The webhook is called when a feedback is submitted.

  • rating (number:1 to 5 or -1 if not specified): The feedback rating score.
  • comments (string): The feedback comment
  • userId (string): The userId from the JWT

For example:

{
   "idempotencyKey":"347cc653-c66c-4ddd-9f89-cd0bbc7a6034",
   "customerId":"143ce1379c35426aa80a902a0204ed09",
   "eventType":"FEEDBACK",
   "sessionId":"be4d177c-a342-41e6-a9b9-8be7ff0b0cc8",
   "timestamp":1623751337550,
   "appId":"vpaas-magic-cookie-143ce1379c35426aa80a902a0204ed09",
   "fqn":"vpaas-magic-cookie-143ce1379c35426aa80a902a0204ed09/testroom2",
   "data":{
      "rating":5,
      "comments":"test feedback",
      "userId":"cd4d177c-b342-41e6-a9b9-8be7ff0b0cc8"
   }
}

DIAL_IN_STARTED:

  • direction (string: in): the direction of the call
  • nick (string): phone number that identifies the caller
  • participantJid (string): unique id of the dial participant

For example:

{
  "timestamp" : 1617182201627,
  "customerId" : "9708f84c111b4c54a8e0374fa4bcb15a",
  "appId":"vpaas-magic-cookie-9708f84c111b4c54a8e0374fa4bcb15a",
  "eventType" : "DIAL_IN_STARTED",
  "idempotencyKey" : "4431e735-b327-4e38-9e29-a8136d4d3624",
  "fqn" : "vpaas-magic-cookie-9708f84c111b4c54a8e0374fa4bcb15a/sampleappempiricalrolesgrabforward",
  "sessionId" : "c808aef2-9bb0-4328-ae1a-dd8bac4dbc66",
  "data" : {
    "direction" : "in",
    "nick" : "40364630871 (+40364630871)",
    "participantJid" : "[email protected]"
  }
}

DIAL_IN_ENDED:

  • participantJid (string): unique id of the dial participant

For example:

{
  "timestamp" : 1617182201627,
  "customerId" : "9708f84c111b4c54a8e0374fa4bcb15a",
  "appId": "vpaas-magic-cookie-9708f84c111b4c54a8e0374fa4bcb15a",
  "eventType" : "DIAL_IN_ENDED",
  "idempotencyKey" : "4431e735-b327-4e38-9e29-a8136d4d3624",
  "fqn" : "vpaas-magic-cookie-9708f84c111b4c54a8e0374fa4bcb15a/sampleappempiricalrolesgrabforward",
  "sessionId" : "c808aef2-9bb0-4328-ae1a-dd8bac4dbc66",
  "data" : {
    "participantJid" : "[email protected]"
  }
}

DIAL_OUT_STARTED:

  • direction (string: out): the direction of the call
  • nick (string): phone number that identifies the caller
  • participantJid (string): unique id of the dial participant

For example:

{
  "timestamp" : 1617182201627,
  "customerId" : "9708f84c111b4c54a8e0374fa4bcb15a",
  "appId": "vpaas-magic-cookie-9708f84c111b4c54a8e0374fa4bcb15a",
  "eventType" : "DIAL_OUT_STARTED",
  "idempotencyKey" : "4431e735-b327-4e38-9e29-a8136d4d3624",
  "fqn" : "vpaas-magic-cookie-9708f84c111b4c54a8e0374fa4bcb15a/sampleappempiricalrolesgrabforward",
  "sessionId" : "c808aef2-9bb0-4328-ae1a-dd8bac4dbc66",
  "data" : {
    "direction" : "out",
    "nick" : "40364630871 (+40364630871)",
    "participantJid" : "[email protected]"
  }
}

DIAL_OUT_ENDED:

  • participantJid (string): unique id of the dial participant

For example:

{
  "timestamp" : 1617182201627,
  "customerId" : "9708f84c111b4c54a8e0374fa4bcb15a",
  "appId": "vpaas-magic-cookie-9708f84c111b4c54a8e0374fa4bcb15a",
  "eventType" : "DIAL_OUT_ENDED",
  "idempotencyKey" : "4431e735-b327-4e38-9e29-a8136d4d3624",
  "fqn" : "vpaas-magic-cookie-9708f84c111b4c54a8e0374fa4bcb15a/sampleappempiricalrolesgrabforward",
  "sessionId" : "c808aef2-9bb0-4328-ae1a-dd8bac4dbc66",
  "data" : {
    "participantJid" : "[email protected]"
  }
}

USAGE:

  • The event happens when each participant joins the meeting. When the first participant joins, MAU notifications are not invoked until the next participants join.
  • data (list) the list contains information about the user that joined. When the second participant joins, the list will have the first two participants. After that, the list will contain only the current participant that joined the meeting.
  • customerId (string): the tenant ID
  • deviceId (string): the random UUID assignment for each participant's device. The UUID identification is not changeable unless the device's local storage is cleared or the participant uses another device (e.g. different browser, phone)
  • email (string): this value can be null if it is not present in the JWT token's context user section.
  • kid (string): the ID that identifies the customer's public key value.
  • userId (string): this value can be null if it is not present in the JWT token's context user section.
  • callDirection (enum: in|out ): this value is for participants that join using their phone. If the participant calls into the meeting callDirection is in. If the participant calls from the meeting callDirection is out. For dial participants, the deviceId is the phone number with JWT related fields not present.

For example:

{
  "idempotencyKey": "251d4ca8-6192-403c-9098-645042679257",
  "customerId": "c2824d584eac4489a1e32e4e164d5a3c",
  "appId": "vpaas-magic-cookie-c2824d584eac4489a1e32e4e164d5a3c",
  "eventType": "USAGE",
  "sessionId": "c3348153-1027-4382-afad-5ae91b433c26",
  "timestamp": 1612354445154,
  "fqn": "vpaas-magic-cookie-c2824d584eac4489a1e32e4e164d5a3c/testroom2",
  "data": [
    {
      "customerId" : "1d2e6a201d594c8f87a630e3f70826d2",
      "deviceId" : "349304d3627f59eac2015f29a9ade613",
      "email" : "[email protected]",
      "kid" : "vpaas-magic-cookie-1d2e6a201d594c8f87a630e3f70826d2/5b3c5a",
      "userId" : "google-oauth2|114025754820379595029"
    }
  ]
}

SPEAKER_STATS:

  • data (map): map between a participant unique identifier (full jid) and the speaker extra information.
  • name (string): The full name of the user
  • avatar (string): The user’s avatar URL
  • id (string): The userId from the jwt
  • time (long): The total time a user spoke in milliseconds.

For example:

{
  "timestamp" : 1617182201627,
  "customerId" : "9708f84c111b4c54a8e0374fa4bcb15a",
  "appId": "vpaas-magic-cookie-9708f84c111b4c54a8e0374fa4bcb15a",
  "eventType" : "SPEAKER_STATS",
  "idempotencyKey" : "4431e735-b327-4e38-9e29-a8136d4d3624",
  "fqn" : "vpaas-magic-cookie-9708f84c111b4c54a8e0374fa4bcb15a/sampleappempiricalrolesgrabforward",
  "sessionId" : "c808aef2-9bb0-4328-ae1a-dd8bac4dbc66",
  "data": {
    "[email protected]/66wbG6MC": {
      "time": 10089,
      "id": "google-oauth2|114025754820379595029",
      "name": "Test user 1",
      "email": "[email protected]"
    },
    "[email protected]/N6GjCJU9": {
      "time": 11277,
      "id": "google-oauth2|114025754820379595030",
      "name": "Test user 2",
      "email": "[email protected]"
    }
  }
}

Did this page help you?