Webhook Notifications

The EnableX Video service uses a server-to-server notification system to push important events to your application in real time. Rather than polling the EnableX API to find out when a session ends, when recordings become available, or when files land on your server — EnableX sends an HTTP POST to your configured Webhook URL the moment each event occurs.

This notification system is the backbone of a well-integrated video workflow. You receive session lifecycle events as they happen, and post-session events (recording ready, files transferred, CDR available) as soon as processing completes — enabling your application to react immediately and efficiently.

Setup

Configure Your Webhook URL

The Webhook URL is a project-level setting — each project can have its own URL, though you can reuse the same URL across multiple projects. EnableX sends all events to the configured URL as HTTP POST requests with a raw JSON body.

To configure your webhook URL:

Log in to the EnableX Portal.
Navigate to My Projects and select the project you want to configure.
Go to Settings → Manage Configuration → Setup Webhook.
Enter your Webhook URL and click Save.

Once saved, EnableX will begin sending all notification events for that project to your URL. The JSON body of every notification contains an app_id field, which you can use to distinguish events across multiple projects sharing the same endpoint.

HTTP Basic Authentication

EnableX supports HTTP Basic Authentication for webhook delivery. When enabled, EnableX includes credentials in the request so your server can verify that the POST is genuinely from EnableX before processing the payload.

To enable this, check the HTTP Authentication checkbox in the webhook configuration screen and enter the username and password you want EnableX to use when calling your endpoint.

Development Testing

Your Webhook URL must be publicly reachable over HTTPS. During local development, use a tunnelling tool such as ngrok http 3000 to expose your local server, then paste the generated HTTPS URL into the portal.

How Notifications Work

Notification Format

Every notification is delivered as an HTTP POST to your webhook URL. The request body is a raw JSON object. The common field across all event types is type, which identifies the event. Your application should inspect type first and then handle the rest of the payload accordingly.

{
  "type": "string",
  "trans_date": 1713600000,
  "app_id": "string",
  "room_id": "string",
  "conf_num": "string"
  ...additional fields per event type
}

Event Type Reference

type value	When it fires
`session_start`	A new session starts in a Video Room.
`session_stop`	An ongoing session ends. Note: CDR is not yet ready at this point.
`roomdrop`	CDR (Call Detail Report) is ready for the ended session.
`recording`	Individual stream recording file(s) are available for download.
`transcoded`	A re-playable transcoded file (from individual recordings) is available.
`live_recording`	A live-recording file (recorded in-session via Custom UI) is available.
`chatdata`	The in-session chat script file is available for download.
`metadata`	The session activity meta data file is available for download.
`transcription`	The session transcription file(s) are available for download.
`file_transfer`	Recording and associated files have been transferred to your delivery destination.

Session Lifecycle Events

Session Started

EnableX posts this notification the moment a new session begins in a Video Room — i.e., when the first participant connects and the conference starts.

{
  "type": "session_start",
  "trans_date": 1713600000,
  "room_id": "string",
  "conf_num": "string",
  "concurrent_sessions": {
    "license_sessions": {
      "$license_id": true
    },
    "total_sessions": 1,
    "max_sessions": 10
  },
  "app_id": "string"
}

concurrent_sessions Object

The concurrent_sessions object is only included if your account uses Concurrency-based Billing. license_sessions appears only under User License Billing. total_sessions reflects how many sessions are currently active, including the new one that just started.

What to do on session_start

Use this event to mark the session as active in your database, start a session timer, or notify stakeholders (e.g., send a push notification to a moderator that the room is live). Save the conf_num — you will need it to correlate all subsequent events for this session.

Session Ended

This notification fires when a session ends — i.e., when all participants have left and the conference closes. The structure mirrors session_start.

{
  "type": "session_stop",
  "trans_date": 1713600000,
  "room_id": "string",
  "conf_num": "string",
  "concurrent_sessions": {
    "license_sessions": {
      "$license_id": false
    },
    "total_sessions": 0,
    "max_sessions": 10
  },
  "app_id": "string"
}

CDR is NOT ready at this point

Do not attempt to fetch the Call Detail Report (CDR) when you receive session_stop. Post-session processing has not completed yet, and an API call to the CDR route will return an empty response. Wait for the roomdrop event before fetching CDR.

CDR Ready

After session processing completes, EnableX posts a roomdrop notification to signal that the Call Detail Report (CDR) is now available. The CDR contains participant-level details, connection durations, and session analytics.

Legacy type name

The type value is roomdrop — a name inherited from an earlier version of the platform. It has not been renamed in order to maintain backward compatibility.

{
  "type": "roomdrop",
  "trans_date": 1713600000,
  "app_id": "string",
  "room_id": "string",
  "conf_num": "string"
}

What to do on roomdrop

This is the correct trigger for fetching CDR. Use the conf_num from this notification to call the Video API CDR route. Do not poll the CDR API on a timer — roomdrop is the authoritative signal that processing is complete and data is available. Store the CDR against your session record in your database.

Recording & File Events

Individual Recordings Ready

When individual stream recording files (one file per participant stream) are ready, EnableX posts a recording notification. The payload includes an array of direct URLs to each file.

{
  "type": "recording",
  "trans_date": 1713600000,
  "app_id": "string",
  "room_id": "string",
  "conf_num": "string",
  "recording": [
    "https://portal.enablex.io/path/file1.mov",
    "https://portal.enablex.io/path/file2.mov"
  ]
}

What to do on recording

The URLs in the recording array are the direct download links for the recording files. If your application needs to store copies locally, loop through the array and download each file — no separate API call required. You can optionally call the Video API Archive route for richer metadata (duration, file size, codec), but the download URLs are already here in the notification. Remember to use HTTP Basic Auth credentials when accessing these URLs — see Recording File Security.

Transcoded File Ready

Individual stream recordings are automatically merged and transcoded into a single re-playable video file. When this transcoded file is ready, EnableX sends a transcoded notification.

{
  "type": "transcoded",
  "trans_date": 1713600000,
  "app_id": "string",
  "room_id": "string",
  "conf_num": "string",
  "recording": "https://portal.enablex.io/path/transcoded.mov",
  "stage": "string",
  "file_size": "string"
}

The stage field indicates the sequence of the transcoded file within the session (useful if the session was long and transcoding produces multiple segments). file_size is in bytes.

What to do on transcoded

The recording field contains the direct download URL for the transcoded file. If your platform surfaces recordings to end users (e.g., a meeting replay link), this is the file to use — it is a single playable video of the full session. Store the URL and file_size against your session record. Apply HTTP Basic Auth when accessing the URL.

Live Recording Ready

If your session used a Custom UI with in-session live recording, this notification fires when the live-recording file is available.

{
  "type": "live_recording",
  "trans_date": 1713600000,
  "app_id": "string",
  "room_id": "string",
  "conf_num": "string",
  "url": "https://portal.enablex.io/path/live.mov",
  "file_size": "string"
}

What to do on live_recording

Use the url field to download or link to the live recording file. Update your database with the URL and file_size. Authentication is required when accessing the file — see Recording File Security.

Chat Data File Ready

When the in-session chat transcript file is available, EnableX posts a chatdata notification. The file captures the full text chat log from the session.

{
  "type": "chatdata",
  "trans_date": 1713600000,
  "app_id": "string",
  "room_id": "string",
  "conf_num": "string",
  "url": "https://portal.enablex.io/path/chat.json"
}

What to do on chatdata

Download the chat file from url and parse it to populate meeting summaries, action item extraction, or compliance archiving. Store the file or its contents against your session record using conf_num as the key.

Meta Data File Ready

The session meta data file contains a structured log of in-session activity — participant join/leave events, stream events, and other session telemetry. EnableX posts this notification when the file is ready.

{
  "type": "metadata",
  "trans_date": 1713600000,
  "app_id": "string",
  "room_id": "string",
  "conf_num": "string",
  "url": "https://portal.enablex.io/path/metadata.json"
}

What to do on metadata

Download and ingest the meta data file to build session analytics, audit trails, or attendance records. This is the most detailed machine-readable record of what happened in the session — more granular than CDR. Use conf_num to associate it with the correct session record.

Transcription File Ready

When Live Transcription is enabled for the room, this notification fires once the transcription file(s) for the session are ready.

{
  "type": "transcription",
  "trans_date": 1713600000,
  "app_id": "string",
  "room_id": "string",
  "conf_num": "string",
  "url": "https://portal.enablex.io/path/transcript.txt"
}

What to do on transcription

Download the transcript from url and use it for meeting notes, full-text search indexing, accessibility records, or AI-based summarisation. Store against the session using conf_num.

Files Transferred

When you have configured Recording Delivery, EnableX transfers your recording and associated files to your chosen destination (FTP/SFTP, SCP, AWS S3, Google Drive, or Azure). Once the transfer completes, this notification is posted.

{
  "type": "file_transfer",
  "trans_date": 1713600000,
  "app_id": "string",
  "room_id": "string",
  "conf_num": "string",
  "destination": {
    "name": "awss3",
    "host": "",
    "account": "my-bucket"
  },
  "files": [
    { "url": "https://my-bucket.s3.amazonaws.com/room_id/conf_num/file1.mov" },
    { "url": "https://my-bucket.s3.amazonaws.com/room_id/conf_num/file2.mov" }
  ]
}

The destination.name field takes one of: awss3, ftp, sftp, ssh. For FTP/SFTP/SCP destinations, host contains the server hostname. For S3, account contains the bucket name.

What to do on file_transfer

The files array contains the final paths of the transferred files at your destination. Update your database to reference these new locations — for example, storing the S3 URLs as the authoritative recording URLs for your session. If you need to reorganise the transferred files into your own folder structure, use the delivered paths as the source and move/copy accordingly, then update your records with the final paths. EnableX organises transferred files into sub-folders named room_id/conf_num at the destination, so you can filter by room or session directly.

Best Practices

Respond Immediately

Your webhook handler must return an HTTP 200 response immediately upon receiving a notification. Do not perform heavy processing synchronously — acknowledge the request first, then process the event asynchronously (e.g., push to a job queue).

If your endpoint does not respond within a reasonable time, EnableX may retry the delivery, leading to duplicate event processing in your application.

Handle Duplicates Gracefully

Webhooks operate on an at-least-once delivery model. The same event may occasionally be delivered more than once. Design your event handlers to be idempotent — use conf_num + type as a deduplication key to avoid processing the same event twice.

Log Raw Payloads

Always log the raw JSON body before parsing. This makes debugging far easier when unexpected event shapes appear, or when you need to replay past events that were not processed correctly.

Handle Unknown Event Types

New event types may be introduced without prior notice. Your handler should accept and return 200 for any event type that it does not explicitly recognise, rather than returning an error. A 4xx or 5xx response on an unknown event type may cause unnecessary retries or delivery failures.