Add Facebook webhook integration for live video notifications

.gitignore

@@ -0,0 +1 @@
+/shimmer/facebook-webhook-log.json

IMPLEMENTATION_SUMMARY.md

@@ -0,0 +1,126 @@
+# Facebook Webhook Implementation Summary
+
+## Overview
+This implementation adds Facebook webhook functionality to the Shimmer WordPress plugin to detect when the Facebook page `/tenth` has a new live video online.
+
+## Files Added/Modified
+
+### New Files
+1. **shimmer/FacebookWebhook.php** - Main webhook handler class
+2. **shimmer/FACEBOOK_WEBHOOK.md** - Setup and configuration documentation
+3. **shimmer/FacebookWebhookTest.php** - Test utilities for verification
+4. **shimmer/facebook-webhook-example.php** - Example demonstrating webhook flow
+
+### Modified Files
+1. **shimmer.php** - Added 3 lines to load and initialize FacebookWebhook class
+
+## Requirements Met
+
+✅ **Requirement 1**: Use webhook API to detect when Facebook page /tenth has new live video
+- Implemented via REST API endpoint at `/wp-json/shimmer/v1/facebook-webhook`
+- Subscribes to `live_videos` field events
+- Processes webhook notifications when status changes to 'live'
+
+✅ **Requirement 2**: Get video ID and provide it to stub method
+- Extracts video ID from webhook payload
+- Calls `FacebookWebhook::handleLiveVideo($videoId)` with the video ID
+- Stub method currently logs the video ID (ready for customization)
+
+✅ **Requirement 3**: Smoothly handle all auth
+- Implements webhook verification (GET endpoint) for Facebook app setup
+- Uses HMAC-SHA256 signature verification for all webhook notifications
+- Supports fallback to SHA1 for older implementations
+- Uses `hash_equals()` for timing-attack-safe comparison
+- Credentials stored as WordPress constants (not in code)
+
+## Technical Implementation
+
+### Webhook Verification (GET)
+When Facebook sets up the webhook subscription:
+1. Facebook sends GET request with `hub.mode`, `hub.verify_token`, and `hub.challenge`
+2. Plugin verifies the token matches `FACEBOOK_WEBHOOK_VERIFY_TOKEN`
+3. Returns the challenge to confirm subscription
+
+### Webhook Notifications (POST)
+When a live video starts on /tenth:
+1. Facebook sends POST request with signed payload
+2. Plugin verifies HMAC signature using `FACEBOOK_APP_SECRET`
+3. Parses payload to extract video information
+4. Calls `handleLiveVideo($videoId)` when status is 'live'
+5. Returns 200 OK to acknowledge receipt
+
+### Security Features
+- ✅ HMAC signature verification (SHA256 or SHA1)
+- ✅ Timing-safe string comparison (`hash_equals()`)
+- ✅ Verify token validation
+- ✅ No hardcoded credentials
+- ✅ Proper error handling
+- ✅ No SQL injection vulnerabilities
+- ✅ No XSS vulnerabilities
+- ✅ Public endpoint only accessible via proper authentication
+
+## Configuration
+
+**Method 1: WordPress Settings Page (Recommended)**
+1. Go to WordPress Admin > Settings > Shimmer
+2. Find the Facebook Webhook section
+3. Enter your Facebook App Secret
+4. Enter your Webhook Verify Token
+5. Click "Save Settings"
+
+**Method 2: wp-config.php (Alternative)**
+Add to `wp-config.php` (for backward compatibility):
+```php
+define('FACEBOOK_APP_SECRET', 'your_app_secret_here');
+define('FACEBOOK_WEBHOOK_VERIFY_TOKEN', 'your_verify_token_here');
+```
+
+Note: Settings page values take precedence over constants.
+
+## Webhook URL
+```
+https://your-wordpress-site.com/wp-json/shimmer/v1/facebook-webhook
+```
+
+## Next Steps for Users
+
+1. Create Facebook App at developers.facebook.com
+2. Add Webhooks product to the app
+3. Configure the callback URL with the webhook endpoint
+4. Subscribe to Page events, specifically the `live_videos` field
+5. Grant the app access to the /tenth Facebook page
+6. Customize `handleLiveVideo($videoId, $videoTitle)` method for specific business logic
+
+## Code Quality
+
+- ✅ PHP syntax validated
+- ✅ Follows WordPress REST API conventions
+- ✅ Proper namespacing (`tp\Shimmer\FacebookWebhook`)
+- ✅ Comprehensive documentation
+- ✅ Test utilities included
+- ✅ Security best practices applied
+- ✅ Minimal changes to existing code
+- ✅ All functionality in new files
+
+## Testing
+
+Test utilities provided in `FacebookWebhookTest.php`:
+- Endpoint registration verification
+- Successful webhook verification test
+- Failed webhook verification test
+- Signature generation example
+- Mock payload creation
+
+Example script in `facebook-webhook-example.php` demonstrates the complete flow.
+
+## Extensibility
+
+The `handleLiveVideo($videoId, $videoTitle)` stub method can be customized to:
+- Create WordPress posts
+- Send email/SMS notifications
+- Update custom fields
+- Trigger recording/archiving
+- Update digital signage
+- Integrate with other systems
+
+Current implementation just logs the video ID and title for verification.

shimmer.php

@@ -12,9 +12,13 @@
 */
 
 use tp\Shimmer\SessionMatters;
+use tp\Shimmer\ShimmerSettings;
+use tp\Shimmer\FacebookWebhook;
 use tp\TouchPointWP\TouchPointWP;
 
 require_once __DIR__ . "/shimmer/SessionMatters.php";
+require_once __DIR__ . "/shimmer/ShimmerSettings.php";
+require_once __DIR__ . "/shimmer/FacebookWebhook.php";
 
 function tenth_involvementClasses()
 {
@@ -400,6 +404,8 @@ function tenth_formatTimeString($string, $t = null): string
 add_filter('tp_adjust_time_string', 'tenth_formatTimeString');
 
 SessionMatters::load();
+ShimmerSettings::load();
+FacebookWebhook::load();
 
 
 /**

shimmer/FACEBOOK_WEBHOOK.md

@@ -0,0 +1,88 @@
+# Facebook Webhook Configuration
+
+This plugin now includes Facebook webhook functionality to detect when the Facebook page `/tenth` has a new live video.
+
+## Setup Instructions
+
+### 1. Facebook App Configuration
+
+1. Go to [Facebook Developers](https://developers.facebook.com/)
+2. Create a new app or use an existing one
+3. Add the "Webhooks" product to your app
+4. In your app settings (Settings > Basic), note down your App Secret
+
+### 2. WordPress Configuration
+
+**Method 1: Using WordPress Settings (Recommended)**
+
+1. In WordPress admin, go to **Settings > Shimmer**
+2. Find the **Facebook Webhook** section
+3. Enter your Facebook App Secret
+4. Create and enter a custom Verify Token (any random string you create - remember it for step 3)
+5. Click "Save Settings"
+
+**Method 2: Using wp-config.php (Alternative)**
+
+For backward compatibility, you can still define these as constants in `wp-config.php`:
+
+```php
+// Facebook App Configuration (optional - settings page is preferred)
+define('FACEBOOK_APP_SECRET', 'your_app_secret_here');
+define('FACEBOOK_WEBHOOK_VERIFY_TOKEN', 'your_verify_token_here');
+```
+
+Note: Settings page values take precedence over constants.
+
+### 3. Webhook Subscription Setup
+
+1. In your Facebook App dashboard, go to Webhooks
+2. Click "Add Callback URL"
+3. Enter your webhook URL: `https://your-site.com/wp-json/shimmer/v1/facebook-webhook`
+4. Enter the Verify Token (the same one you entered in WordPress settings)
+5. Click "Verify and Save"
+
+### 4. Subscribe to Page Events
+
+1. In the Webhooks section, find your Page subscription
+2. Click "Add Subscriptions"
+3. Select the `live_videos` field
+4. Save the subscription
+
+### 5. Grant Permissions
+
+1. Your Facebook App needs permission to access the page
+2. Go to your Facebook Page settings
+3. Add your app with appropriate permissions
+
+## How It Works
+
+When a live video is started on the Facebook page `/tenth`:
+
+1. Facebook sends a POST request to the webhook endpoint
+2. The request is verified using the app secret
+3. The webhook payload is parsed to extract the video ID and title
+4. The `FacebookWebhook::handleLiveVideo($videoId, $videoTitle)` method is called with the video ID and title
+
+## Customization
+
+The stub method `FacebookWebhook::handleLiveVideo($videoId, $videoTitle)` currently just logs the video ID and title. You can customize this method in `/shimmer/FacebookWebhook.php` to:
+
+- Create a WordPress post
+- Send notifications
+- Update custom fields
+- Trigger other actions
+
+## Testing
+
+To test the webhook:
+
+1. Use Facebook's webhook testing tool in the App dashboard
+2. Send a test event for `live_videos`
+3. Check your WordPress error logs for the message: "Facebook Live Video Detected - Video ID: {id}"
+
+## Security
+
+- All webhook requests are verified using HMAC signature validation
+- The verify token prevents unauthorized webhook subscriptions
+- Both GET (verification) and POST (notifications) endpoints are properly secured
+- Credentials are stored securely in WordPress options table