From 80a89306a399b9df806ead879810f9bf2a0fd1cf Mon Sep 17 00:00:00 2001 From: Andy Dixon Date: Mon, 10 Nov 2025 15:35:40 +0000 Subject: [PATCH] first commit --- README.md | 182 ++++++++++++++++++++ docs.htm | 491 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ index.php | 202 ++++++++++++++++++++++ 3 files changed, 875 insertions(+) create mode 100644 README.md create mode 100644 docs.htm create mode 100755 index.php diff --git a/README.md b/README.md new file mode 100644 index 0000000..2948038 --- /dev/null +++ b/README.md @@ -0,0 +1,182 @@ +# Webhook Email Forwarder + +A simple, elegant PHP solution for debugging webhooks by forwarding them directly to your email. + +## 🌟 Features + +- **Email Delivery**: Receive complete webhook data directly in your inbox +- **Secure**: Built-in email validation and XSS protection +- **Instant**: Real-time webhook processing and forwarding +- **Simple**: No database or complex setup required +- **Universal**: Supports all HTTP methods and content types + +## 📋 Overview + +This webhook service captures incoming HTTP requests and forwards complete request details (headers, body, metadata) to your specified email address. Perfect for debugging webhooks, testing integrations, and monitoring API callbacks. + +## 🚀 Quick Start + +### 1. Encode Your Email +Replace `@` with `%40` in your email address: +- `test@example.com` becomes `test%40example.com` + +### 2. Configure Webhook +Use the following URL format as your webhook endpoint: +``` +https://your-domain.com/{encoded-email} +``` + +### 3. Check Your Inbox +Receive detailed webhook data instantly in your email with the subject: +``` +‼️ Webhook Request Received - [timestamp] +``` + +## 💡 Usage Examples + +### cURL - POST Request with JSON +```bash +curl -X POST https://your-domain.com/test%40example.com \ + -H "Content-Type: application/json" \ + -d '{"event": "user.created", "user_id": 12345}' +``` + +### cURL - GET Request with Parameters +```bash +curl https://your-domain.com/test%40example.com?event=test&id=123 +``` + +### JavaScript - Fetch API +```javascript +fetch('https://your-domain.com/test%40example.com', { + method: 'POST', + headers: { + 'Content-Type': 'application/json', + }, + body: JSON.stringify({ + event: 'order.completed', + order_id: 'ORD-789', + total: 99.99 + }) +}); +``` + +### Python - Requests Library +```python +import requests + +response = requests.post( + 'https://your-domain.com/test%40example.com', + json={'event': 'payment.received', 'amount': 250.00}, + headers={'X-Custom-Header': 'MyValue'} +) +print(response.text) +``` + +## 📦 Installation + +1. Clone the repository: +```bash +git clone https://github.com/andydixon/webhook.git +``` + +2. Upload the files to your web server (ensure PHP is installed and configured) + +3. Ensure the web server has permission to send emails (PHP `mail()` function) + +4. Access the root URL to view the documentation page + +## 🔧 Requirements + +- PHP 7.0 or higher +- Web server (Apache, Nginx, etc.) +- PHP `mail()` function enabled +- Outbound SMTP/email capability + +## 📧 What You Receive + +Each webhook email contains: + +- **Request Timestamp**: Exact date and time when the webhook was received +- **Request Information**: IP address, HTTP method, and Content-Type +- **Request Headers**: All HTTP headers sent with the request +- **Request Body**: Complete raw body content (JSON, XML, form data, etc.) +- **PHP Variables**: Parsed GET, POST, REQUEST, and FILES superglobals + +## 🔒 Security Features + +- **Email Validation**: Only valid email addresses are accepted +- **XSS Protection**: All output is sanitized using `htmlspecialchars()` +- **No Data Storage**: Webhook data is forwarded immediately and not stored +- **Error Logging**: Failed email attempts are logged for monitoring + +> **Privacy Note**: Anyone with your webhook URL can send data to your email address. Only use this service for testing and debugging purposes. Do not use for sensitive production data without additional authentication. + +## ✅ Supported Features + +### HTTP Methods +- GET, POST, PUT, PATCH, DELETE +- Any custom HTTP method + +### Content Types +- application/json +- application/x-www-form-urlencoded +- multipart/form-data +- text/plain +- text/xml +- Any custom content type + +## 🎯 Common Use Cases + +- **Debugging**: See exactly what data third-party services are sending +- **Integration Testing**: Test webhook integrations before implementing full handlers +- **Monitoring**: Monitor webhook activity and payload changes over time +- **Documentation**: Capture real examples for API documentation +- **Development**: Quickly test webhook flows during development +- **Troubleshooting**: Diagnose issues with webhook payloads and headers + +## 💡 Tips & Best Practices + +- **Email Filtering**: Create an email filter for the subject line "‼️ Webhook Request Received" to organize incoming webhooks +- **Plus Addressing**: Use email plus addressing (e.g., `yourname+github%40gmail.com`) to track which services are sending webhooks +- **Timestamp in Emails**: Check the "Date Received" field to verify webhook timing and debug delivery delays +- **Parse the Body**: The raw body section contains the exact payload - perfect for copying into your code for testing + +## 📝 Error Handling + +### Invalid Email Address +If the email address in the URL is invalid or missing: +``` +HTTP 400 Bad Request +Invalid email address provided in URL path. +``` + +## 📄 License + +This project is licensed under the GNU General Public License v3.0 - see the [LICENSE](LICENSE) file for details. + +## 👤 Author + +**Andy Dixon** +- Website: [andydixon.com](https://andydixon.com) +- GitHub: [@andydixon](https://github.com/andydixon) + +## 🤝 Contributing + +Contributions, issues, and feature requests are welcome! Feel free to check the [issues page](https://github.com/andydixon/webhook/issues). + +## ⭐ Show Your Support + +Give a ⭐️ if this project helped you! + +## 📜 Version History + +- **1.0.0** - Initial release + - Basic webhook forwarding functionality + - HTML email formatting + - Email validation and XSS protection + - Documentation page + +--- + +Built with PHP and ADHD medication 💊 diff --git a/docs.htm b/docs.htm new file mode 100644 index 0000000..a1dc5cd --- /dev/null +++ b/docs.htm @@ -0,0 +1,491 @@ + + + + + + Webhook Email Forwarder - Documentation + + + + + +
+ +
+

Webhook Email Forwarder

+

A simple, elegant solution for debugging webhooks by forwarding them directly to your email

+

Version 1.0 | Made with ❤️ by Andy Dixon

+
+ + +
+

Overview

+

This webhook service captures incoming HTTP requests and forwards complete request details (headers, body, metadata) to your specified email address.

+ +
+
+
+
+ +
Email Delivery
+

Receive webhook data directly in your inbox

+
+
+
+
+
+
+ +
Secure
+

Email validation and XSS protection built-in

+
+
+
+
+
+
+ +
Instant
+

Real-time webhook processing and forwarding

+
+
+
+
+
+ + +
+

How It Works

+
    +
  1. You configure a third-party service to send webhooks to this URL with your email encoded in the path
    2. +
  2. When a webhook request arrives, the service captures all request data
    3. +
  3. The complete request details are formatted into a readable HTML email
    4. +
  4. The email is sent to your specified address
    5. +
  5. A confirmation response is returned to the webhook sender
    6. +
+ +
+ Perfect for: Debugging webhooks, testing integrations, monitoring API callbacks, and understanding third-party service payloads. +
+
+ + +
+

Usage

+ +

Basic URL Format

+

The URL format is simple - just append your URL-encoded email address to the domain:

+
+https:///{email-address} +
+ +

URL Encoding Your Email

+

The @ symbol must be URL-encoded as %40:

+ +
+
+
+
+ Original Email +
+
+ john@example.com +
+
+
+
+
+
+ Webhook URL +
+
+ /john%40example.com +
+
+
+
+ +

Example Requests

+ +

cURL - POST Request with JSON

+
+curl -X POST https:///test%40example.com \ + -H "Content-Type: application/json" \ + -d '{"event": "user.created", "user_id": 12345}' +
+ +

cURL - GET Request with Parameters

+
+curl https:///test%40example.com?event=test&id=123 +
+ +

JavaScript - Fetch API

+
+fetch('https:///test%40example.com', { + method: 'POST', + headers: { + 'Content-Type': 'application/json', + }, + body: JSON.stringify({ + event: 'order.completed', + order_id: 'ORD-789', + total: 99.99 + }) +}); +
+ +

Python - Requests Library

+
+import requests + +response = requests.post( + 'https:///test%40example.com', + json={'event': 'payment.received', 'amount': 250.00}, + headers={'X-Custom-Header': 'MyValue'} +) +print(response.text) +
+ +
+ Important: Make sure to URL-encode your email address. Most programming languages and tools have built-in functions for this (e.g., encodeURIComponent() in JavaScript, urllib.parse.quote() in Python). +
+
+ + +
+

What to Expect

+ +

Immediate HTTP Response

+

When your webhook is successfully received, you'll get an immediate response:

+
+
+ HTTP 200 OK +
+
+
+Webhook received and forwarded to: test@example.com + +Request data: +Array +( + [event] => test + [id] => 123 +) +
+
+
+ +

Email Contents

+

Within moments, you'll receive a styled HTML email containing:

+ +
+
+
+
+
Request Timestamp
+

Exact date and time when the webhook was received

+
+
+
+
+
+
+
Request Information
+

IP address, HTTP method (GET/POST/etc), and Content-Type

+
+
+
+
+
+
+
Request Headers
+

All HTTP headers sent with the request

+
+
+
+
+
+
+
Request Body
+

Complete raw body content (JSON, XML, form data, etc.)

+
+
+
+
+
+
+
PHP Variables
+

Parsed GET, POST, REQUEST, and FILES superglobals for easy access

+
+
+
+
+ +
+ Subject Line: Emails arrive with the subject "‼️ Webhook Request Received - [timestamp]" for easy filtering and identification. +
+
+ + +
+

Error Handling

+ +

Invalid Email Address

+

If the email address in the URL is invalid or missing, you'll receive:

+
+
+ HTTP 400 Bad Request +
+
+
+Invalid email address provided in URL path. +
+
+
+ +
+ Validation: The service validates email addresses using PHP's built-in FILTER_VALIDATE_EMAIL filter to ensure proper formatting. +
+
+ + +
+

Security Features

+
    +
  • Email Validation: Only valid email addresses are accepted
    • +
  • XSS Protection: All output is sanitized using htmlspecialchars()
    • +
  • No Data Storage: Webhook data is forwarded immediately and not stored on the server
    • +
  • Error Logging: Failed email attempts are logged for monitoring
    • +
+ +
+ Privacy Note: Anyone with your webhook URL can send data to your email address. Only use this service for testing and debugging purposes. Do not use for sensitive production data without additional authentication. +
+
+ + +
+

Supported Features

+ +
+
+
HTTP Methods
+
    +
  • GET
    • +
  • POST
    • +
  • PUT
    • +
  • PATCH
    • +
  • DELETE
    • +
  • Any custom method
    • +
+
+
+
Content Types
+
    +
  • application/json
    • +
  • application/x-www-form-urlencoded
    • +
  • multipart/form-data
    • +
  • text/plain
    • +
  • text/xml
    • +
  • Any custom content type
    • +
+
+
+
+ + +
+

Common Use Cases

+ +
+
+
+
+
Debugging
+

See exactly what data third-party services are sending to your webhooks

+
+
+
+
+
+
+
Integration Testing
+

Test webhook integrations before implementing full handlers

+
+
+
+
+
+
+
Monitoring
+

Monitor webhook activity and payload changes over time

+
+
+
+
+
+
+
Documentation
+

Capture real examples for API documentation

+
+
+
+
+
+
+
Development
+

Quickly test webhook flows during development

+
+
+
+
+
+
+
Troubleshooting
+

Diagnose issues with webhook payloads and headers

+
+
+
+
+
+ + +
+

Tips & Best Practices

+ +
+
Email Filtering
+

Create an email filter for the subject line "‼️ Webhook Request Received" to organize incoming webhooks in your inbox.

+
+ +
+
Use Plus Addressing
+

Use email plus addressing (e.g., yourname+github%40gmail.com) to track which services are sending webhooks.

+
+ +
+
Timestamp in Emails
+

Check the "Date Received" field in emails to verify webhook timing and debug delivery delays.

+
+ +
+
Parse the Body
+

The raw body section contains the exact payload - perfect for copying into your code for testing.

+
+
+ + +
+

Quick Start

+

Get started in 3 simple steps:

+ +
+
+
+
+
1
+
Encode Your Email
+

Replace @ with %40 in your email address

+
+
+
+
+
+
+
2
+
Configure Webhook
+

Use /{your-email} as the webhook URL

+
+
+
+
+
+
+
3
+
Check Your Inbox
+

Receive detailed webhook data instantly in your email

+
+
+
+
+ +
+
Try it now!
+
+curl -X POST https:///YOUR-EMAIL-HERE \ + -d '{"test": "Hello World!"}' +
+
+
+ + +
+

Built with PHP and ADHD medication

+

© 2025-2026 Andy Dixon |

+
+
+ + + + diff --git a/index.php b/index.php new file mode 100755 index 0000000..8dabba7 --- /dev/null +++ b/index.php @@ -0,0 +1,202 @@ +/email%40domain.com + * + * @author Dixon + * @version 1.0 + */ + +// Prevent any output buffering issues +if (ob_get_level()) { + ob_end_clean(); +} + +// Retrieve the complete request URI from the server superglobal +$requestUri = $_SERVER['REQUEST_URI'] ?? ''; + +// Parse the URL to extract only the path component, excluding any query strings +// This ensures that any GET parameters don't interfere with email extraction +$path = parse_url($requestUri, PHP_URL_PATH); + +// Remove leading and trailing forward slashes from the path +// Example: '/email%40domain.com/' becomes 'email%40domain.com' +$emailEncoded = trim($path, '/'); + +// Decode the URL-encoded email address (e.g., %40 becomes @) +// Example: 'email%40domain.com' becomes 'email@domain.com' +$email = urldecode($emailEncoded); + +if(empty($email)) { + include'docs.htm'; + die(); +} + +// Validate the extracted email address using PHP's built-in filter +// This ensures the email is in a valid format before proceeding +if (!filter_var($email, FILTER_VALIDATE_EMAIL)) { + // Set HTTP response code to 400 Bad Request + http_response_code(400); + // Return error message to the client + echo 'Invalid email address provided in URL path.'; + // Terminate script execution + exit; +} + +// Capture the current date and time when the webhook request was received +// Format: YYYY-MM-DD HH:MM:SS (24-hour format) +$dateReceived = date('Y-m-d H:i:s'); + +// Retrieve the IP address of the client making the request +// Note: This may be a proxy IP if behind a load balancer or CDN +$ipAddress = $_SERVER['REMOTE_ADDR'] ?? 'Unknown'; + +// Capture the HTTP method used for this request (GET, POST, PUT, DELETE, etc.) +$requestMethod = $_SERVER['REQUEST_METHOD'] ?? 'Unknown'; + +// Retrieve the Content-Type header sent by the client +// Use null coalescing operator to provide a default if not set +$contentType = $_SERVER['CONTENT_TYPE'] ?? 'N/A'; + +// Retrieve all HTTP headers sent with the request +// getallheaders() returns an associative array of all headers +$headersArray = getallheaders(); + +// Initialize an empty string to store formatted headers +$headersText = ''; + +// Iterate through each header and format it as "Key: Value" +foreach ($headersArray as $key => $value) { + // Concatenate each header on a new line + $headersText .= htmlspecialchars($key, ENT_QUOTES, 'UTF-8') . ': ' . + htmlspecialchars($value, ENT_QUOTES, 'UTF-8') . "\n"; +} + +// Read the raw request body from the input stream +// php://input allows access to the raw POST data regardless of Content-Type +$rawBody = file_get_contents('php://input'); + +// Sanitise the raw body for HTML output to prevent XSS attacks +$rawBodySafe = htmlspecialchars($rawBody, ENT_QUOTES, 'UTF-8'); + +// Compile all PHP superglobal variables into an array for debugging purposes +// This provides visibility of all data received with the request +$variables = [ + '_GET' => $_GET, + '_POST' => $_POST, + '_REQUEST' => $_REQUEST, + '_FILES' => $_FILES, +]; + +// Convert the variables array to a human-readable string format +// The second parameter (true) makes print_r return the output instead of printing it +$variablesText = print_r($variables, true); + +// Sanitise the variables text for HTML output +$variablesTextSafe = htmlspecialchars($variablesText, ENT_QUOTES, 'UTF-8'); + +// Sanitise individual metadata fields for HTML output +$dateReceivedSafe = htmlspecialchars($dateReceived, ENT_QUOTES, 'UTF-8'); +$ipAddressSafe = htmlspecialchars($ipAddress, ENT_QUOTES, 'UTF-8'); +$requestMethodSafe = htmlspecialchars($requestMethod, ENT_QUOTES, 'UTF-8'); +$contentTypeSafe = htmlspecialchars($contentType, ENT_QUOTES, 'UTF-8'); + +// Construct the HTML email body using a heredoc string for better readability +// This creates a styled HTML email with all webhook details +$html = << + + + + + Webhook Request Received + + + + +

Request Received

+ 
Date: $dateReceivedSafe
+ + +

Request Information

+ 
IP Address: $ipAddressSafe
+Request Method: $requestMethodSafe
+Content-Type: $contentTypeSafe
+ + +

Request Headers

+ 
$headersText
+ + +

Request Body

+ 
$rawBodySafe
+ + +

PHP Variables

+ 
$variablesTextSafe
+ + +HTML; + +// Construct the email subject line with an attention-grabbing emoji and timestamp +$subject = "‼️ Webhook Request Received - $dateReceived"; + +// Build email headers to ensure proper HTML rendering and sender information +// MIME-Version declares email format capabilities +$emailHeaders = "MIME-Version: 1.0\r\n"; +// Content-type specifies HTML email with UTF-8 character encoding +$emailHeaders .= "Content-type: text/html; charset=UTF-8\r\n"; +// From header sets the sender address to a no-reply address on the same domain +$emailHeaders .= "From: no-reply@" . ($_SERVER['SERVER_NAME'] ?? 'localhost') . "\r\n"; + +// Send the email using PHP's built-in mail function +// Parameters: recipient, subject, message body, headers +$mailSent = mail($email, $subject, $html, $emailHeaders); + +// Check if the email was sent successfully +if (!$mailSent) { + // Log error or handle failure (note: mail() return value is unreliable on some systems) + error_log("Failed to send webhook email to: $email"); +} + +// Set the Content-Type header for the HTTP response to plain text +header('Content-Type: text/plain; charset=UTF-8'); + +// Return a simple acknowledgement to the webhook sender +// This confirms the webhook was received and processed +echo "Webhook received and forwarded to: $email\n\n"; + +// Include a sanitised copy of the REQUEST data in the response for debugging +echo "Request data:\n"; +print_r($_REQUEST);