Ozeki SMS Gateway - Webhook Tester
====================================

A PHP-based webhook receiver for testing the webhook notification system
of the Ozeki Android SMS Gateway.

REQUIREMENTS
------------
- PHP 7.4 or higher
- A web server (Apache, Nginx, or WAMP/XAMPP)
- Write permission on the webhook-tester directory for log file creation

INSTALLATION
------------

Option A: WAMP (Windows)
1. Copy the entire "Webhook" folder to C:\wamp64\www\Webhook\
2. Start WAMP (ensure Apache and PHP are running)
3. Open http://localhost/Webhook/ in your browser

Option B: XAMPP (Windows)
1. Copy the entire "Webhook" folder to C:\xampp\htdocs\Webhook\
2. Start XAMPP (ensure Apache is running)
3. Open http://localhost/Webhook/ in your browser

Option C: Linux (Apache + PHP)
1. Copy the files to /var/www/html/webhook-tester/
   sudo cp -r Webhook/* /var/www/html/webhook-tester/
2. Set write permissions for the log file:
   sudo chown -R www-data:www-data /var/www/html/webhook-tester/
   sudo chmod -R 755 /var/www/html/webhook-tester/
   sudo chmod 666 /var/www/html/webhook-tester/webhook-log.json (after first request)
3. Open http://your-server-ip/webhook-tester/ in your browser

FOLDER PERMISSIONS
------------------
The webhook-log.json file is created automatically on the first request.
If you get permission errors:
- Windows: Right-click the Webhook folder > Properties > Security >
  Ensure "Users" have Write permission.
- Linux: Run: sudo chmod 777 /path/to/Webhook/
  (or better: sudo chown www-data:www-data /path/to/Webhook/)

CONFIGURING WEBHOOK URLs IN OZEKI SMS GATEWAY
----------------------------------------------
Open the Ozeki SMS Gateway web GUI (http://<phone-ip>:9532) and go to
the Webhooks tab. Register one of these URLs:

Default endpoint (receives all events):
  http://<your-server-ip>/Webhook/webhook-receiver.php

Delivery reports only:
  http://<your-server-ip>/Webhook/webhook-receiver.php?type=delivery

Incoming messages only:
  http://<your-server-ip>/Webhook/webhook-receiver.php?type=incoming

Outgoing status only:
  http://<your-server-ip>/Webhook/webhook-receiver.php?type=outgoing

TESTING ERROR HANDLING
----------------------
Timeout test (5-second delay before response):
  http://<your-server-ip>/Webhook/webhook-receiver.php?delay=5

Server error test (returns HTTP 500):
  http://<your-server-ip>/Webhook/webhook-receiver.php?status=500

Combined test (delay + error):
  http://<your-server-ip>/Webhook/webhook-receiver.php?delay=3&status=503

SENDING TEST REQUESTS VIA CURL
-------------------------------
You can test the receiver manually:

  curl -X POST http://localhost/Webhook/webhook-receiver.php \
    -H "Content-Type: application/json" \
    -d '{
      "event": "incoming_message",
      "timestamp": "2025-01-01T12:00:00Z",
      "webhook_id": "test-123",
      "data": {
        "message_id": "msg-001",
        "from": "+1234567890",
        "text": "Hello world",
        "subscription_id": 1,
        "sim_slot_index": 0
      }
    }'

  curl -X POST http://localhost/Webhook/webhook-receiver.php \
    -H "Content-Type: application/json" \
    -d '{
      "event": "outgoing_status",
      "timestamp": "2025-01-01T12:01:00Z",
      "webhook_id": "test-123",
      "data": {
        "message_id": "msg-002",
        "status": "sent",
        "to": "+0987654321",
        "subscription_id": 1,
        "attempt": 1,
        "total_parts": 1,
        "successful_parts": 1,
        "failed_parts": 0
      }
    }'

  curl -X POST http://localhost/Webhook/webhook-receiver.php \
    -H "Content-Type: application/json" \
    -d '{
      "event": "delivery_report",
      "timestamp": "2025-01-01T12:02:00Z",
      "webhook_id": "test-123",
      "data": {
        "message_id": "msg-002",
        "delivery_status": "delivered",
        "to": "+0987654321",
        "subscription_id": 1,
        "delivery_date": "2025-01-01T12:01:30Z"
      }
    }'

  curl -X POST "http://localhost/Webhook/webhook-receiver.php?status=500" \
    -H "Content-Type: application/json" \
    -d '{"event": "outgoing_status", "timestamp": "2025-01-01T12:00:00Z", "webhook_id": "test", "data": {"message_id": "m1", "status": "sent"}}'

HMAC SIGNATURE VERIFICATION
-----------------------------
If you set a webhook secret in the Ozeki SMS Gateway, the receiver will
log the X-Webhook-Signature header. To verify the signature on the server
side, add this PHP code:

  $secret = 'your-webhook-secret';
  $expectedSignature = hash_hmac('sha256', $rawBody, $secret);
  $receivedSignature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
  if (!hash_equals($expectedSignature, $receivedSignature)) {
      // Signature mismatch - reject or flag
  }

WEB INTERFACE
-------------
Open http://localhost/Webhook/ to see the web interface with:
- Real-time event log (auto-refreshes every 5 seconds)
- Event filtering by type
- JSON payload viewer with syntax highlighting
- Log download and clear functions
- Statistics summary

COMMON ISSUES
-------------
1. "Permission denied" writing webhook-log.json
   -> Ensure the web server user has write access to the Webhook directory.

2. Webhooks not reaching the server
   -> Check firewall rules allow incoming HTTP on port 80/443.
   -> Verify the URL is accessible from the phone's network.
   -> Ensure the phone and server are on the same network or the server
      has a public IP.

3. Webhook returns 404
   -> Verify the file path matches the URL. On Apache, ensure mod_rewrite
      is enabled if using URL rewriting. On WAMP, check the alias/vhost config.

4. JSON validation warnings
   -> The webhook receiver validates that payloads contain required fields
      (event, timestamp, webhook_id, data). Missing fields generate warnings
      but the webhook is still accepted (HTTP 200).

5. Log file grows too large
   -> The receiver keeps the last 500 entries. Use the "Clear Log" button
      in the web interface to reset, or delete webhook-log.json manually.

FILE STRUCTURE
--------------
  Webhook/
  ├── index.php              - Web interface for viewing webhook events
  ├── webhook-receiver.php   - Webhook receiver endpoint (POST handler)
  ├── webhook-log.json       - Log file (auto-created on first request)
  ├── style.css              - Stylesheet for the web interface
  └── README.txt             - This file