# 100ms Webhook Configuration

## Overview
This document explains how to configure 100ms webhooks to automatically handle meeting events and update participant status in the database.

## Webhook Endpoint
```
POST https://your-domain.com/schedule/webhook/100ms
```

## 100ms Dashboard Configuration

1. **Login to 100ms Dashboard**
   - Go to https://dashboard.100ms.live
   - Navigate to your project

2. **Configure Webhook**
   - Go to "Webhooks" section
   - Click "Add Webhook"
   - Set the webhook URL: `https://your-domain.com/schedule/webhook/100ms`
   - Enable the following events:
     - `peer.join.success` - When a participant joins (for logging/debugging)
     - `session.close.success` - When a meeting session ends
     - `peer.leave.success` - When a participant leaves
     - `beam.stopped.success` - When recording/streaming stops

3. **Webhook Events Handled**

### peer.join.success
Triggered when a participant joins the meeting.
- Logs detailed join information for debugging
- Shows user data, role, peer ID, and timestamp
- Helps verify webhook integration is working
- Does not modify database (logging only)

### session.close.success
Triggered when a meeting session is closed/ended.
- Updates meeting status to COMPLETED
- Sets endedAt timestamp
- Updates all active participants' leftAt time
- Calculates watch duration for each participant
- Sets leaveReason to 'meeting_ended_by_100ms'

### peer.leave.success
Triggered when a participant leaves the meeting.
- Updates individual participant's leftAt time
- Calculates watch duration
- Sets leaveReason to 'peer_left_100ms'

### beam.stopped.success
Triggered when recording/streaming stops.
- Currently acknowledged but not processed
- Can be extended for recording management

## Sample Webhook Payload

### Peer Join Event
```json
{
  "type": "peer.join.success",
  "data": {
    "room_id": "room-abc-123",
    "peer_id": "peer-xyz-456",
    "user_data": "{\"userId\":\"user-123\"}",
    "role": "host",
    "joined_at": "2023-10-14T12:00:00Z"
  }
}
```

### Session Close Event
```json
{
  "type": "session.close.success",
  "data": {
    "room_id": "room-abc-123",
    "session_id": "session-def-456",
    "timestamp": "2023-10-14T12:00:00Z"
  }
}
```

### Peer Leave Event
```json
{
  "type": "peer.leave.success",
  "data": {
    "room_id": "room-abc-123",
    "peer_id": "peer-ghi-789",
    "user_data": "{\"userId\":\"user-123\"}",
    "timestamp": "2023-10-14T12:00:00Z"
  }
}
```

## Database Updates

The webhook handler updates the following database tables:

### Schedule Table
- `status`: Updated to COMPLETED when session closes
- `endedAt`: Set to webhook timestamp

### ScheduleParticipant Table
- `leftAt`: Set to webhook timestamp
- `watchDuration`: Calculated as (leftAt - joinedAt) in seconds
- `leaveReason`: Set based on event type

## Testing

To test the webhook:

1. **Local Development**
   ```bash
   # Use ngrok to expose local server
   ngrok http 3000
   
   # Use the ngrok URL in 100ms dashboard
   https://abc123.ngrok.io/schedule/webhook/100ms
   ```

2. **Manual Testing**
   ```bash
   curl -X POST https://your-domain.com/schedule/webhook/100ms \
     -H "Content-Type: application/json" \
     -d '{
       "type": "session.close.success",
       "data": {
         "room_id": "your-room-id",
         "session_id": "test-session"
       }
     }'
   ```

## Monitoring

Check the application logs for webhook processing:
- Successful processing: "Meeting X ended via 100ms webhook"
- Errors: "Error handling session close event"

## Security Considerations

1. **IP Whitelisting**: Consider whitelisting 100ms webhook IPs
2. **Signature Verification**: 100ms provides webhook signatures for verification
3. **Rate Limiting**: Implement rate limiting on the webhook endpoint

## Environment Variables

No additional environment variables required for basic webhook functionality.
For signature verification (recommended for production):
```
HMS_WEBHOOK_SECRET=your-webhook-secret
```