diff --git a/DEPLOYMENT_phase2.md b/DEPLOYMENT_phase2.md
index 412d60f..08c9b63 100644
--- a/DEPLOYMENT_phase2.md
+++ b/DEPLOYMENT_phase2.md
@@ -101,10 +101,10 @@ LOG_LEVEL=WARNING
 # Box.com automation
 BOX_CONFIG_PATH=../oliver_box_config.json
 BOX_VIDEO_OPTIMIZER_FOLDER_ID=362124323515
-BOX_AS_USER_ID=
-BOX_WEBHOOK_SECRET=
-BOX_USE_POLLING=false
-BOX_POLL_INTERVAL_SECONDS=60
+BOX_AS_USER_ID=                          # leave blank — JWT app scopes handle access directly
+BOX_WEBHOOK_SECRET=                      # set this if using webhook mode (see Box Webhook Setup section below)
+BOX_USE_POLLING=true                     # true = poll IN folder every 60s (simplest, no webhook needed)
+BOX_POLL_INTERVAL_SECONDS=60             # set to false + configure webhook for instant processing
 ```
 
 Secure the credentials files:
@@ -160,24 +160,31 @@ sudo systemctl status video-optimizer-backend
 ## Step 6 — Verify Deployment
 
 ```bash
-# Service status
+# 1. Service status
 sudo systemctl status video-optimizer-backend
 
-# Backend health check (local)
+# 2. Backend health check (local)
 curl http://localhost:5000/api/health
 # Expected: {"status":"ok","ffmpeg_installed":true,"timestamp":"..."}
 
-# Backend health check (through Apache)
+# 3. Backend health check (through Apache/public URL)
 curl https://ai-sandbox.oliver.solutions/video-optimizer/api/health
 
-# Box automation status (optional)
+# 4. Box automation status (local)
+curl http://localhost:5000/api/box/health
+# Expected: {"box_available":true,"box_initialised":true,"folders_configured":true,...}
+
+# 5. Box automation status (through Apache)
+curl https://ai-sandbox.oliver.solutions/video-optimizer/api/box/health
+
+# 6. Box full diagnostic (run as www-data to match service account)
 sudo -u www-data /opt/video-optimizer-back/venv/bin/python \
     /opt/video-optimizer-back/backend/box_setup.py
 ```
 
 Then open in browser:
 - `https://ai-sandbox.oliver.solutions/video-optimizer` — main app (requires SSO login)
-- `https://ai-sandbox.oliver.solutions/video-optimizer/admin.html` — admin panel
+- `https://ai-sandbox.oliver.solutions/video-optimizer/admin.html` — admin panel (includes Box history tab)
 
 ---
 
@@ -260,6 +267,57 @@ sudo systemctl reload apache2
 
 ---
 
+## Box Automation — Polling vs Webhook
+
+The application supports two modes for monitoring the Box IN folder:
+
+### Option A — Polling (recommended to start with)
+No Box configuration needed. The service checks the IN folder every 60 seconds.
+
+```env
+BOX_USE_POLLING=true
+BOX_POLL_INTERVAL_SECONDS=60
+BOX_WEBHOOK_SECRET=         # leave blank
+```
+
+Restart the service after changing `.env`:
+```bash
+sudo systemctl restart video-optimizer-backend
+```
+
+Files dropped into Box IN will be processed within 60 seconds automatically.
+
+### Option B — Webhook (instant processing, requires Box Admin setup)
+Box calls the server immediately when a file is uploaded — no polling delay.
+
+**Step 1 — Generate a webhook secret:**
+```bash
+python3 -c "import secrets; print(secrets.token_hex(32))"
+```
+
+**Step 2 — Add to `.env` on the server:**
+```env
+BOX_USE_POLLING=false
+BOX_WEBHOOK_SECRET=<secret-generated-above>
+```
+
+**Step 3 — Configure the webhook in Box Admin Console:**
+- Go to [app.box.com/master](https://app.box.com/master) → Admin Console → Integrations → Webhooks
+- Create a new webhook:
+  - **URL:** `https://ai-sandbox.oliver.solutions/webhooks/box`
+  - **Trigger events:** `FILE.UPLOADED`, `FILE.COPIED`
+  - **Target:** VIDEO_OPTIMIZER IN folder (ID: `362125331342`)
+  - **Primary key:** paste the secret from Step 1
+
+**Step 4 — Restart:**
+```bash
+sudo systemctl restart video-optimizer-backend
+```
+
+Files uploaded to Box IN will trigger the pipeline within seconds.
+
+---
+
 ## Quick Reference
 
 ```bash
@@ -314,6 +372,14 @@ sudo -u www-data /opt/video-optimizer-back/venv/bin/python \
     /opt/video-optimizer-back/backend/box_setup.py
 # Check .env has BOX_VIDEO_OPTIMIZER_FOLDER_ID=362124323515
 # Check oliver_box_config.json exists and is readable by www-data
+curl http://localhost:5000/api/box/health
+```
+
+**Test Box pipeline manually (replace FILE_ID with a real Box file ID from IN folder):**
+```bash
+curl -X POST http://localhost:5000/api/box/trigger \
+  -H "Content-Type: application/json" \
+  -d '{"file_id": "FILE_ID", "filename": "campaign_tiktok_9x16.mp4"}'
 ```
 
 **Frontend changes not showing:**