From c26ce650833d264654176a54dba3f57386638541 Mon Sep 17 00:00:00 2001 From: Mathieu Virbel Date: Tue, 2 Sep 2025 18:09:44 -0600 Subject: [PATCH] feat: update Jitsi documentation with webhook events storage system MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add comprehensive webhook event storage documentation - Document event structure and JSON storage in meetings table - Add practical webhook testing examples with proper signature generation - Include detailed troubleshooting for webhook signature verification issues - Add webhook event payload examples for all supported event types - Document event storage verification and database querying methods - Enhance existing webhook configuration with real-world examples 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- docs/video-jitsi.md | 174 ++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 161 insertions(+), 13 deletions(-) diff --git a/docs/video-jitsi.md b/docs/video-jitsi.md index 1b6788d4..e44e97e9 100644 --- a/docs/video-jitsi.md +++ b/docs/video-jitsi.md @@ -194,6 +194,45 @@ Component "conference.meet.example.com" "muc" "jibri-recording-on", "jibri-recording-off" } + +#### Webhook Event Payload Examples + +**Participant Joined Event:** +```json +{ + "event": "muc-occupant-joined", + "room": "reflector-my-room-uuid123", + "timestamp": "2025-01-15T10:30:00.000Z", + "data": { + "occupant_id": "participant-456", + "nick": "John Doe", + "role": "participant", + "affiliation": "none" + } +} +``` + +**Recording Started Event:** +```json +{ + "event": "jibri-recording-on", + "room": "reflector-my-room-uuid123", + "timestamp": "2025-01-15T10:32:00.000Z", + "data": { + "recording_id": "rec-789", + "initiator": "moderator-123" + } +} +``` + +**Recording Completed Event:** +```json +{ + "room_name": "reflector-my-room-uuid123", + "recording_file": "/var/recordings/rec-789.mp4", + "recording_status": "completed", + "timestamp": "2025-01-15T11:15:00.000Z" +} ``` ### 4. Jibri Recording Setup (Optional) @@ -359,12 +398,41 @@ Reflector automatically generates JWT tokens with: - `"automatic"` - Start immediately - `"automatic-2nd-participant"` - Start when 2nd person joins -### Event Tracking +### Event Tracking and Storage -Automatic participant tracking via webhooks: -- Join/leave events update participant counts -- Recording state changes trigger processing -- Real-time meeting analytics +Reflector automatically stores all webhook events in the `meetings` table for comprehensive meeting analytics: + +**Supported Event Types:** +- `muc-occupant-joined` - Participant joined the meeting +- `muc-occupant-left` - Participant left the meeting +- `jibri-recording-on` - Recording started +- `jibri-recording-off` - Recording stopped +- `recording_completed` - Recording file ready for processing + +**Event Storage Structure:** +Each webhook event is stored as a JSON object in the `meetings.events` column: +```json +{ + "type": "muc-occupant-joined", + "timestamp": "2025-01-15T10:30:00.123456Z", + "data": { + "timestamp": "2025-01-15T10:30:00Z", + "user_id": "participant-123", + "display_name": "John Doe" + } +} +``` + +**Querying Stored Events:** +```sql +-- Get all events for a meeting +SELECT events FROM meeting WHERE id = 'meeting-uuid'; + +-- Count participant joins +SELECT json_array_length( + json_extract(events, '$[*] ? (@.type == "muc-occupant-joined")') +) as total_joins FROM meeting WHERE id = 'meeting-uuid'; +``` ## Testing and Verification @@ -399,17 +467,49 @@ echo "Test meeting URL: $MEETING" ### Webhook Testing -Test event webhook manually: +#### Manual Webhook Event Testing + +Test participant join event: ```bash +# Generate proper signature +PAYLOAD='{"event":"muc-occupant-joined","room":"reflector-test-room-uuid","timestamp":"2025-01-15T10:30:00.000Z","data":{"user_id":"test-user","display_name":"Test User"}}' +SIGNATURE=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$JITSI_WEBHOOK_SECRET" | cut -d' ' -f2) + curl -X POST "https://your-reflector-domain.com/v1/jitsi/events" \ -H "Content-Type: application/json" \ - -H "X-Jitsi-Signature: test-signature" \ - -d '{ - "event": "muc-occupant-joined", - "room": "test-room-name", - "timestamp": "2025-01-15T10:30:00.000Z", - "data": {} - }' + -H "X-Jitsi-Signature: $SIGNATURE" \ + -d "$PAYLOAD" +``` + +Expected response: +```json +{ + "status": "ok", + "event": "muc-occupant-joined", + "room": "reflector-test-room-uuid" +} +``` + +#### Recording Webhook Testing + +Test recording completion event: +```bash +PAYLOAD='{"room_name":"reflector-test-room-uuid","recording_file":"/recordings/test.mp4","recording_status":"completed","timestamp":"2025-01-15T10:30:00.000Z"}' +SIGNATURE=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$JITSI_WEBHOOK_SECRET" | cut -d' ' -f2) + +curl -X POST "https://your-reflector-domain.com/v1/jibri/recording-complete" \ + -H "Content-Type: application/json" \ + -H "X-Jitsi-Signature: $SIGNATURE" \ + -d "$PAYLOAD" +``` + +#### Event Storage Verification + +Verify events were stored: +```bash +# Check meeting events via API (requires authentication) +curl -H "Authorization: Bearer $AUTH_TOKEN" \ + "https://your-reflector-domain.com/v1/meetings/{meeting-id}" ``` ## Troubleshooting @@ -451,6 +551,54 @@ curl -v "https://your-reflector-domain.com/v1/jitsi/health" sudo tail -f /var/log/prosody/prosody.log ``` +#### Webhook Signature Verification Issues + +**Symptoms**: HTTP 401 "Invalid webhook signature" errors + +**Solutions**: +1. Verify webhook secret matches between Jitsi and Reflector +2. Check payload encoding (no extra whitespace) +3. Ensure proper HMAC-SHA256 signature generation + +**Debug signature generation**: +```bash +# Test signature manually +PAYLOAD='{"event":"test","room":"test","timestamp":"2025-01-15T10:30:00.000Z","data":{}}' +SECRET="your-webhook-secret-here" + +# Generate signature (should match X-Jitsi-Signature header) +echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET" | cut -d' ' -f2 + +# Test with curl +curl -X POST "https://your-reflector-domain.com/v1/jitsi/events" \ + -H "Content-Type: application/json" \ + -H "X-Jitsi-Signature: $(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET" | cut -d' ' -f2)" \ + -d "$PAYLOAD" -v +``` + +#### Event Storage Problems + +**Symptoms**: Events received but not stored in database + +**Solutions**: +1. Check database connectivity and permissions +2. Verify meeting exists before event processing +3. Review Reflector application logs +4. Ensure JSON column support in database + +**Debug event storage**: +```bash +# Check meeting exists +curl -H "Authorization: Bearer $TOKEN" \ + "https://your-reflector-domain.com/v1/meetings/{meeting-id}" + +# Monitor database queries (if using PostgreSQL) +sudo -u postgres psql -c "SELECT * FROM pg_stat_activity WHERE query LIKE '%meeting%';" + +# Check Reflector logs for event processing +sudo journalctl -u reflector -f | grep -E "(event|webhook|jitsi)" +``` + #### Recording Issues **Symptoms**: Recordings not starting, finalize script errors