Webhooks Guide

Webhooks allow your application to receive real-time events from EazyClassroom. Instead of polling the API for changes, you can listen for events like a student joining a session or a recording becoming available.

How Webhooks Work

1. You register a webhook_url for your API client (via the admin dashboard or API).
2. When an event occurs (e.g., a participant joins a session), EazyClassroom sends an HTTP POST request to your URL.
3. Your server processes the event (e.g., updates your database, sends a notification).
4. You respond with HTTP 200 OK to acknowledge receipt.

Important: Webhooks are sent only to the URL registered for your API client. You can have only one webhook URL per client (multiple endpoints can be added on request).

Registering a Webhook URL

As an admin:

1. Go to Settings -> API Clients.
2. Edit your API client.
3. Enter the webhook_url (e.g., https://yourdomain.com/webhook/eazyclassroom).
4. Enter a webhook_secret (a random string used to sign payloads - generate one, e.g., using openssl rand -hex 32).
5. Save.

Alternatively, you can set these fields directly in the api_clients table via SQL.

Webhook Events

Event	Trigger	Payload Fields
participant.joined	A user joins a session	meeting_id, user_name, user_id (if provided), role
participant.left	A user leaves a session	Same as above
chat.message	A chat message is sent (public or private)	meeting_id, user_name, message, timestamp
meeting.ended	The session ends (automatically or via API)	meeting_id, duration, recording_ready (boolean)

Payload Structure

All webhook requests have the following JSON body:

{
  "event": "participant.joined",
  "meeting_id": "math-class",
  "timestamp": "2026-06-08T10:05:00Z",
  "data": {
    "user_name": "John Doe",
    "user_id": "student_123",
    "role": "VIEWER"
  }
}