Webhooks

11.0 Webhooks

We can POST, to a url of your choice, details of certain events related to conferences. Please contact us to set up your endpoint. We would need to know:

• The endpoint URL
• Which events (see 11.2 et seq) you are interested in. (Or all events.)

11.1 Generalities

Webhook events are sent using HTTP POST, with body type of JSON.

The header contains the x-signing-token (accessible from the Developers section in Admin UI) as a way to validate the requests are indeed coming from us.

The body contains 3 keys:

• event: string, the type of event, conference_start, conference_end, etc. See values in the individual sections below
• payload: string, escaped and serialized JSON representing details of about the event, which depend on the type, see below.
• timestamp string, the timestamp of the event in ISO 8601 format.

POST

Request header:
content-type: application/json
x-signing-token: ...token...

Request body:
{
  "event": "conference_end",
  "payload": "{\"conference_id\":1258835,\"host_id\":61803}",
  "timestamp": "2022-08-24T20:56:55.000Z"`
}

11.2 Conference Start

• event: conference_start
• payload
  • host_id: unique identifier for the conference’s host (can be used with host methods above)
  • company_id: unique identifier for the company the conference’s host belongs to (can be used with company methods above)
  • conference_id: unique identifier for the conference (can be used with conference methods above)

11.3 Conference End

• event: conference_end
• payload
  • host_id: unique identifier for the conference’s host (can be used with host methods above)
  • company_id: unique identifier for the company the conference’s host belongs to (can be used with company methods above)
  • conference_id: unique identifier for the conference (can be used with conference methods above)

11.4 Start Recording

• event: start_recording
• payload
  • host_id: unique identifier for the conference’s host (can be used with host methods above)
  • company_id: unique identifier for the company the conference’s host belongs to (can be used with company methods above)
  • conference_id: unique identifier for the conference (can be used with conference methods above)

11.5 Stop Recording

• event: stop_recording
• payload
  • host_id: unique identifier for the conference’s host (can be used with host methods above)
  • company_id: unique identifier for the company the conference’s host belongs to (can be used with company methods above)
  • conference_id: unique identifier for the conference (can be used with conference methods above)

11.6 Start Streaming

• event: start_streaming
• payload
  • host_id: unique identifier for the conference’s host (can be used with host methods above)
  • company_id: unique identifier for the company the conference’s host belongs to (can be used with company methods above)
  • conference_id: unique identifier for the conference (can be used with conference methods above)

11.7 Stop Streaming

• event: stop_streaming
• payload
  • host_id: unique identifier for the conference’s host (can be used with host methods above)
  • company_id: unique identifier for the company the conference’s host belongs to (can be used with company methods above)
  • conference_id: unique identifier for the conference (can be used with conference methods above)

11.8 Recording Ready

• event: recording_ready
• payload
  • host_id: unique identifier for the conference’s host (can be used with host methods above)
  • company_id: unique identifier for the company the conference’s host belongs to (can be used with company methods above)
  • conference_id: unique identifier for the conference (can be used with conference methods above)
  • recording_id: unique identifier for the recording
  • download_link: a link directly to the mp3 of an audio recording, or mp4 of a video recording

11.9 Transcription Ready

• event: transcription_ready
• payload
  • host_id: unique identifier for the conference’s host (can be used with host methods above)
  • company_id: unique identifier for the company the conference’s host belongs to (can be used with company methods above)
  • conference_id: unique identifier for the conference (can be used with conference methods above)

11.10 Enter Livestream

• event: enter_livestream
• payload
  • host_id: unique identifier for the conference’s host (can be used with host methods above)
  • company_id: unique identifier for the company the conference’s host belongs to (can be used with company methods above)
  • conference_id: unique identifier for the conference (can be used with conference methods above)
  • participant_id: unique identifier for the participant

11.11 Leave Livestream

• event: leave_livestream
• payload
  • host_id: unique identifier for the conference’s host (can be used with host methods above)
  • company_id: unique identifier for the company the conference’s host belongs to (can be used with company methods above)
  • conference_id: unique identifier for the conference (can be used with conference methods above)
  • participant_id: unique identifier for the participant
  • reason_for_leaving: one of user_exit, user_dropped, host_kicked, host_kicked_blocked for each of the possible ways to leave a livestream

11.12 Stream Preview Updated

• event: stream_preview_updated
• payload
  • host_id: unique identifier for the conference’s host (can be used with host methods above)
  • company_id: unique identifier for the company the conference’s host belongs to (can be used with company methods above)
  • conference_id: unique identifier for the conference (can be used with conference methods above)
  • video_url: S3 link containing the video preview file in mp4 format
  • image_url: (Optional) S3 link containing the image preview file in jpg format

11.13 Profile Picture Upload Success

• event: profile_picture_upload_success
• payload
  • host_id: unique identifier for the conference’s host (can be used with host methods above)
  • company_id: unique identifier for the company the conference’s host belongs to (can be used with company methods above)

11.14 Profile Picture Upload Failure

• event: profile_picture_upload_failure
• payload
  • host_id: unique identifier for the conference’s host (can be used with host methods above)
  • company_id: unique identifier for the company the conference’s host belongs to (can be used with company methods above)

11.15 Enter Conference

• event: enter_conference
• payload
  • host_id: unique identifier for the conference’s host (can be used with host methods above)
  • company_id: unique identifier for the company the conference’s host belongs to (can be used with company methods above)
  • conference_id: unique identifier for the conference (can be used with conference methods above)
  • participant_id: unique identifier for the participant
  • participant_role: role of the participant, one of organizer, moderator, or participant
  • meeting_url: meeting URL of the conference/meeting entered

11.16 Leave Conference

• event: leave_conference
• payload
  • host_id: unique identifier for the conference’s host (can be used with host methods above)
  • company_id: unique identifier for the company the conference’s host belongs to (can be used with company methods above)
  • conference_id: unique identifier for the conference (can be used with conference methods above)
  • participant_id: unique identifier for the participant
  • participant_role: role of the participant, one of organizer, moderator, or participant
  • reason_for_leaving: one of user_exit, user_dropped, host_kicked, host_kicked_blocked for each of the possible ways to leave a conference

11.17 Dialout Status Change

• event: dialout_status_change
• payload

  • host_id: unique identifier for the conference’s host (can be used with host methods above)

  • company_id: unique identifier for the company the conference’s host belongs to (can be used with company methods above)

  • conference_id: unique identifier for the conference (can be used with conference methods above)

  • participant_id: unique identifier for the participant

  • status: one of:

    • new - request enqueued, but not yet fetched by the dialout infrastructure

    • dialed - dialed but not yet answered ('ringing')

    • answered - answered and playing invitation

    • rejected - participant rejected call, either actively (pressed 2) or passively (hung up)

    • noanswer - participant did not answer

    • cancelled - cancelled by the system before joining or rejecting

    • notenabled - dialout feature not enabled for a host/company

      N.B. there is no discrete ‘joined’ status; if the dialed participant joins by pressing 1, there will be separate a ‘enter_conference’ (q.v. above) webhook event.

  • phone_number: the dialed participant’s own phone number

11.18 Participant Role Changed

• event: participant_role_changed
• payload
  • host_id: unique identifier for the conference’s host (can be used with host methods above)
  • conference_id: unique identifier for the conference (can be used with conference methods above)
  • participant_id: unique identifier for the participant
  • participant_role: role of the participant, one of organizer, moderator, or participant

11.19 Pre-recorded Stream Started

• event: start_broadcasting
• payload
  • host_id: unique identifier for the conference’s host (can be used with host methods above)
  • company_id: unique identifier for the company the conference’s host belongs to (can be used with company methods above)
  • conference_id: unique identifier for the conference (can be used with conference methods above)

11.20 Pre-recorded Stream Stopped

• event: stop_broadcasting
• payload
  • host_id: unique identifier for the conference’s host (can be used with host methods above)
  • company_id: unique identifier for the company the conference’s host belongs to (can be used with company methods above)
  • conference_id: unique identifier for the conference (can be used with conference methods above)

11.21 Drive File Added

• event: drive_file_added (after /drive/file/finish_upload is called AND internal processing is completed)
• payload
  • host_id: unique identifier for the conference’s host (can be used with host methods above)
  • company_id: unique identifier for the company the conference’s host belongs to (can be used with company methods above)
  • id
  • filename
  • size

11.22 Drive File Deleted

• event: drive_file_deleted
• payload
  • host_id: unique identifier for the conference’s host (can be used with host methods above)
  • company_id: unique identifier for the company the conference’s host belongs to (can be used with company methods above)
  • id
  • filename

11.23 One-time Access Code Reused

• event: one_time_access_code_reused
• payload
  • host_id: unique identifier for the conference’s host (can be used with host methods above)
  • company_id: unique identifier for the company the conference’s host belongs to (can be used with company methods above)
  • conference_id: unique identifier for the new conference (can be used with conference methods above)
  • original_conference_id: unique identifier for the original conference, i.e. that for which the access code was originally generated (can be used with conference methods above)