Web hooks

Overview

White label instance can be configured to call web hooks implemented by third-party systems whenever a certain event happens in the system. For instance, if a third-party system needs to be informed whenever a meeting is scheduled, one can configure the white label instance accordingly ("Web hooks" section of the System Configuration)

The system implements the following web hooks:

• onMeetingScheduled: called whenever a new meeting was scheduled
• onMeetingUpdated: called whenever a meeting was updated
• onMeetingClosed: called whenever a meeting was closed (automatically or manually)
• onMeetingDeleted: called whenever a meeting was deleted
• onMeetingSummaryCreated: called whenever a meeting summary was created (usually around 5 minutes after the meeting was closed)
• onMeetingRecordingCreated: called whenever a recorded meeting was merged.
• onMeetingJoined: called whenever someone joins a meeting.
• onMeetingLeft: called whenever someone leaves a meeting.

HTTP Methods

The HTTP service which listens for web hook calls can expect HTTP POST or HTTP PUT calls. Each web hook can be configured separately in the system.

API Key protection

Each web hook can be configured with an individual API key to protect the service from being called by unauthorized third parties. If an API Key is configured it will always be sent as a HTTP header X-API-KEY.

HTTP Payload

The web hooks onMeetingScheduled, onMeetingUpdated and onMeetingClosed will be called with a Meeting object as JSON:

{
  "invitedParticipants": [],
  "meetingId": "9974-7653-8886-0485",
  "id": "5e945c36b863b82cefdddf54",
  "topic": "My Meeting Topic",
  "startTime": "2024-04-07T09:00:00.000Z",
  "endTime": "2024-04-07T10:00:00.000Z",
  "duration": "60",
  "type": "standard",
  "roomId": "5e9459c5b863b82cefdddf50",
  "isRecurring": false,
  "isDialin": false,
  "recurring": {
    "frequencyType": "",
    "frequency": null,
    "monthlyPattern": "",
    "endsType": "",
    "endsOn": "2024-04-13T12:18:07.211Z",
    "endsAfter": 0
  },
  "isRecorded": false,
  "agenda": "",
  "documents": [],
  "meetingPermissionId": null,
  "videoResolution": "standard",
  "dtClosedAt": null,
  "whitelabelId": "5c737902b377b0f7fbf81fce",
  "addedByUserId": "5e9459c5b863b82cefdddf4e",
  "addedByUserEmail": "test-user@example.com",
  "accountId": "5e9459c5b863b82cefdddf4f",
  "addedByUserName": "Test User",
  "timezone": "Europe/Zurich",
  "privateDataVisible": true,
  "icalSequence": "0",
  "icsToken": "c89f842f-3295-4bf9-807d-a46841fbc2ec-25f722e4-70fc-4163-9cda-b4b7d8aec358",
  "isActive": false,
  "isClosed": true,
  "isOpen": false,
  "dialInConferenceRoom": null,
  "dialInNumbers": [],
  "dialInPin": null,
  "sipProxy": null,
  "sipDomain": null,
  "isDemo": false,
  "isPromo": false
}

The web hook onMeetingDeleted will be called with an array of Meeting objects (in may be that multiple meetings were deleted at the same time).

[ 
  {
    "invitedParticipants": [],
    "meetingId": "9974-7653-8886-0485",
    "id": "5e945c36b863b82cefdddf54",
    "topic": "My Meeting Topic",
    "startTime": "2024-04-07T09:00:00.000Z",
    "endTime": "2024-04-07T10:00:00.000Z",
    "duration": "60",
    "type": "standard",
    "roomId": "5e9459c5b863b82cefdddf50",
    "isRecurring": false,
    "isDialin": false,
    "recurring": {
      "frequencyType": "",
      "frequency": null,
      "monthlyPattern": "",
      "endsType": "",
      "endsOn": "2024-04-13T12:18:07.211Z",
      "endsAfter": 0
    },
    "isRecorded": false,
    "agenda": "",
    "documents": [],
    "meetingPermissionId": null,
    "videoResolution": "standard",
    "dtClosedAt": null,
    "whitelabelId": "5c737902b377b0f7fbf81fce",
    "addedByUserId": "5e9459c5b863b82cefdddf4e",
    "addedByUserEmail": "test-user@example.com",
    "accountId": "5e9459c5b863b82cefdddf4f",
    "addedByUserName": "Test User",
    "timezone": "Europe/Zurich",
    "privateDataVisible": true,
    "icalSequence": "0",
    "icsToken": "c89f842f-3295-4bf9-807d-a46841fbc2ec-25f722e4-70fc-4163-9cda-b4b7d8aec358",
    "isActive": false,
    "isClosed": true,
    "isOpen": false,
    "dialInConferenceRoom": null,
    "dialInNumbers": [],
    "dialInPin": null,
    "sipProxy": null,
    "sipDomain": null,
    "isDemo": false,
    "isPromo": false
  }
]

The web hook onMeetingSummaryCreated will be called with a MeetingSummary object in JSON format:

{
  "responseCode": 0,
  "data": {
    "id": "5f7d49eb62e8f9a43b23f986",
    "meetingId": "5f7d49e662e8f9a43b23f983",
    "meetingType": "boardroom",
    "agenda": "",
    "minutes": "",
    "participants": [
      {
        "name": "Participant 1",
        "durations": [
          {
            "action": "joined",
            "timestamp": 1602046445811
          },
          {
            "action": "left",
            "timestamp": 1602046670808
          },
          {
            "action": "joined",
            "timestamp": 1602047908378
          },
          {
            "action": "left",
            "timestamp": 1602048304208
          }
        ],
        "info": {
          "browserVersion": "82.0.4062.0",
          "browserName": "Chrome",
          "osName": "macOS",
          "osVersion": "10.15.6",
          "platformType": "desktop",
          "platformVendor": "Apple"
        }
      },
      {
        "name": "Participant 2",
        "durations": [
          {
            "action": "joined",
            "timestamp": 1602046456329
          },
          {
            "action": "left",
            "timestamp": 1602046669443
          }
        ],
        "info": {
          "browserVersion": "82.0.4062.0",
          "browserName": "Chrome",
          "osName": "macOS",
          "osVersion": "10.15.6",
          "platformType": "desktop",
          "platformVendor": "Apple"
        }
      }
    ],
    "documents": [],
    "pdf": null,
    "dayTimestamp": 1602021600000,
    "accountId": "5c73790ab377b0f7fbf81fde",
    "isNamedRoom": false,
    "isRecordingPrepared": false,
    "sfuHostname": "ch-01-sfu-02.wlvmr.net",
    "meetingQuestions": [],
    "meetingConversationDuration": 25,
    "meetingConversationStartToEndDuration": 25,
    "meetingParticipantsStartToEndDuration": 35,
    "meetingStartToEndDuration": 60,
  }
}

The parameters meetingConversationDuration, meetingConversationStartToEndDuration, meetingParticipantsStartToEndDuration and meetingStartToEndDuration are defined as follows:

onMeetingRecordingCreated will be called with a MeetingRecordingPrepared object in JSON format:

{
  "meetingId": "5e945c36b863b82cefdddf54",
  "meetingSummaryId": "5f48a701ee0c388a879bffa7",
  "meetingToken": "f7140700-310e-46b8-9813-be0cb0e6b59c",
  "mergedRecordingUrl": "https://..../<merged-file>.webm",
  "recordingUrls": [
    "video-file-1.webm",
    "video-file-2.webm",
    "video-file-3.webm"
  ]
}

Finally, the onMeetingJoined and onMeetingLeft will be called with a MeetingParticipantsStatus object in JSON format:

{
  "meetingId":  "5df78199c015b37195230596",
  "meetingToken":  "0000-0000-0000-0000",
  "participant":  {
    "participantName": "Joe Doe",
    "participantEmail": "joe@example.com",
    "participantMeetingUUID": "4edaf0d2-cb6c-42f1-a266-4ae7d971f2e6",
    "isModerator": false
  },
  "totalNumberOfGuests": 3,
  "totalNumberOfModerators": 1
}