diff --git a/README.md b/README.md index 2948038..0bdb246 100644 --- a/README.md +++ b/README.md @@ -5,10 +5,12 @@ A simple, elegant PHP solution for debugging webhooks by forwarding them directl ## 🌟 Features - **Email Delivery**: Receive complete webhook data directly in your inbox +- **Custom Parsers**: Beautifully formatted emails for GitHub and other services - **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 +- **Extensible**: Easy to add new parsers for any webhook service ## 📋 Overview @@ -21,19 +23,70 @@ 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: +Use one of the following URL formats as your webhook endpoint: + +**Standard format** (raw webhook data): ``` https://your-domain.com/{encoded-email} ``` +**With parser** (formatted email for specific services): +``` +https://your-domain.com/{encoded-email}/{parser-name} +``` + ### 3. Check Your Inbox -Receive detailed webhook data instantly in your email with the subject: +Receive webhook data instantly in your email! + +**Standard format:** ``` ‼️ Webhook Request Received - [timestamp] ``` +**With parser:** +``` +📤 GitHub push - username/repo +💳 Stripe payment.succeeded - $99.99 +``` + +## 🎨 Webhook Parsers + +Parsers format webhooks from specific services into beautiful, readable emails. + +### Available Parsers + +#### GitHub (`/github`) +Formats GitHub webhook events with full event details. + +**Supported events:** +- Push events (with commit details) +- Pull requests +- Issues +- Releases +- And more... + +**Example URL:** +``` +https://your-domain.com/test%40example.com/github +``` + +**What you get:** +- Event-specific formatting +- Commit details with author info +- Pull request/issue metadata +- Clean, scannable layout +- Relevant emojis for quick identification + +### Creating Your Own Parser + +Want to add support for Stripe, GitLab, or other services? Check out the [**Parser Development Guide**](../PARSER_PROMPT.md) for detailed instructions on creating custom parsers. + +--- + ## 💡 Usage Examples +### Standard Webhook (Raw Data) + ### cURL - POST Request with JSON ```bash curl -X POST https://your-domain.com/test%40example.com \ @@ -73,6 +126,40 @@ response = requests.post( print(response.text) ``` +### With GitHub Parser + +Configure your GitHub webhook with: +``` +https://your-domain.com/yourname%40company.com/github +``` + +When events occur, you'll receive formatted emails like: + +**Push Event:** +``` +📤 GitHub push - yourname/your-repo + +Repository: yourname/your-repo +Branch: refs/heads/main +Commits: 3 +Pusher: developerUsername + +Commits: +abc1234 Fix bug in authentication by John Doe +def5678 Update dependencies by Jane Smith +ghi9012 Add new feature by Bob Johnson +``` + +**Pull Request:** +``` +🔀 GitHub pull_request (opened) - yourname/your-repo + +Number: #42 +Title: Add new authentication method +State: open +Branch: feature-auth → main +``` + ## 📦 Installation 1. Clone the repository: @@ -129,18 +216,22 @@ Each webhook email contains: ## 🎯 Common Use Cases - **Debugging**: See exactly what data third-party services are sending +- **GitHub Notifications**: Get beautifully formatted emails for pushes, PRs, and issues - **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 +- **Custom Parsers**: Add your own parsers for Stripe, GitLab, Slack, etc. ## 💡 Tips & Best Practices -- **Email Filtering**: Create an email filter for the subject line "‼️ Webhook Request Received" to organize incoming webhooks +- **Use Parsers**: Use `/github`, `/stripe`, etc. for prettier emails from supported services +- **Email Filtering**: Create email filters based on subject patterns ("📤 GitHub", "💳 Stripe") to organize 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 +- **Standard Format**: Use the standard format (no parser) when you need complete raw data for debugging +- **Create Parsers**: Build custom parsers for your favorite services - see [Parser Guide](../PARSER_PROMPT.md) ## 📝 Error Handling @@ -171,6 +262,13 @@ Give a ⭐️ if this project helped you! ## 📜 Version History +- **2.0.0** - Parser System Release + - ✨ **NEW**: Custom parser support for formatted webhooks + - ✨ **NEW**: GitHub webhook parser with full event support + - ✨ **NEW**: Parser development guide (PARSER_PROMPT.md) + - Backward compatible with existing webhook URLs + - Same security and styling standards + - **1.0.0** - Initial release - Basic webhook forwarding functionality - HTML email formatting diff --git a/index.php b/index.php index 8dabba7..805795b 100755 --- a/index.php +++ b/index.php @@ -24,8 +24,12 @@ $requestUri = $_SERVER['REQUEST_URI'] ?? ''; $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, '/'); +// Example: '/email%40domain.com/' or '/email%40domain.com/github' +$pathParts = explode('/', trim($path, '/')); + +// Extract email and optional parser +$emailEncoded = $pathParts[0] ?? ''; +$parserName = $pathParts[1] ?? null; // Decode the URL-encoded email address (e.g., %40 becomes @) // Example: 'email%40domain.com' becomes 'email@domain.com' @@ -105,9 +109,29 @@ $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 = << $dateReceived, + 'ip' => $ipAddress, + 'method' => $requestMethod, + 'contentType' => $contentType + ]); + + if ($parsed !== false) { + $html = $parsed['html']; + $subject = $parsed['subject']; + } +} + +// If no parser or parser failed, use default format +if (empty($html)) { + // Construct the HTML email body using a heredoc string for better readability + // This creates a styled HTML email with all webhook details + $html = << @@ -115,70 +139,661 @@ $html = << Webhook Request Received - -

Request Received

- 
Date: $dateReceivedSafe
+
+ +
+

⚡ Webhook Request Received

+

$dateReceivedSafe

+
- -

Request Information

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

Request Headers

- 
$headersText
+ +
+
📨 Request Headers
+ 
$headersText
+
- -

Request Body

- 
$rawBodySafe
+ +
+
📦 Request Body
+ 
$rawBodySafe
+
- -

PHP Variables

- 
$variablesTextSafe
+ +
+
🔧 PHP Variables
+ 
$variablesTextSafe
+
+ + +
+

This webhook was automatically forwarded to your email address.

+
+
HTML; -// Construct the email subject line with an attention-grabbing emoji and timestamp -$subject = "‼️ Webhook Request Received - $dateReceived"; + // Construct the email subject line with an attention-grabbing emoji and timestamp + $subject = "‼️ Webhook Request Received - $dateReceived"; +} + +/** + * Helper function to render nested arrays/objects as HTML tables + * + * @param array $data The data to render + * @param int $depth Current recursion depth + * @return string HTML representation of the data + */ +function renderDataAsTable($data, $depth = 0) { + if ($depth > 10) { + return '
Max depth reached
'; + } + + $html = ''; + + if (!is_array($data)) { + $safe = htmlspecialchars((string)$data, ENT_QUOTES, 'UTF-8'); + return "
$safe
"; + } + + // Check if it's an indexed array of similar items (like commits) + $isIndexedArray = array_keys($data) === range(0, count($data) - 1); + + if ($isIndexedArray && count($data) > 0) { + // Render as a list of items + foreach ($data as $index => $item) { + if (is_array($item)) { + $html .= '
'; + $html .= '
Item ' . ($index + 1) . '
'; + $html .= '
'; + foreach ($item as $key => $value) { + $keySafe = htmlspecialchars($key, ENT_QUOTES, 'UTF-8'); + + if (is_array($value)) { + $html .= '
'; + $html .= '
' . $keySafe . '
'; + $html .= '
'; + $html .= renderDataAsTable($value, $depth + 1); + $html .= '
'; + $html .= '
'; + } else { + $valueSafe = htmlspecialchars((string)$value, ENT_QUOTES, 'UTF-8'); + $html .= '
'; + $html .= '
' . $keySafe . '
'; + $html .= '
' . $valueSafe . '
'; + $html .= '
'; + } + } + $html .= '
'; + $html .= '
'; + } else { + $valueSafe = htmlspecialchars((string)$item, ENT_QUOTES, 'UTF-8'); + $html .= '
• ' . $valueSafe . '
'; + } + } + } else { + // Render as key-value table + $html .= '
'; + foreach ($data as $key => $value) { + $keySafe = htmlspecialchars($key, ENT_QUOTES, 'UTF-8'); + + if (is_array($value) && !empty($value)) { + // Close current table and start a subsection + $html .= '
'; + $html .= '
'; + $html .= '
' . $keySafe . '
'; + $html .= renderDataAsTable($value, $depth + 1); + $html .= '
'; + $html .= '
'; + } else if (is_array($value) && empty($value)) { + $html .= '
'; + $html .= '
' . $keySafe . '
'; + $html .= '
empty
'; + $html .= '
'; + } else { + $valueSafe = htmlspecialchars((string)$value, ENT_QUOTES, 'UTF-8'); + $html .= '
'; + $html .= '
' . $keySafe . '
'; + $html .= '
' . $valueSafe . '
'; + $html .= '
'; + } + } + $html .= '
'; + } + + return $html; +} + +/** + * GitHub Webhook Parser + * Parses GitHub webhook events into a formatted email + * + * @param string $rawBody The raw request body + * @param array $headers The request headers + * @param array $metadata Request metadata (date, ip, method, contentType) + * @return array|false Array with 'html' and 'subject' keys, or false on failure + */ +function githubParse($rawBody, $headers, $metadata) { + $payload = json_decode($rawBody, true); + if (!$payload) { + return false; + } + + // Determine event type from headers + $event = $headers['X-GitHub-Event'] ?? $headers['X-Github-Event'] ?? 'Unknown'; + $delivery = $headers['X-GitHub-Delivery'] ?? $headers['X-Github-Delivery'] ?? 'Unknown'; + + // Extract common data + $action = $payload['action'] ?? null; + $repository = $payload['repository']['full_name'] ?? 'Unknown'; + $sender = $payload['sender']['login'] ?? 'Unknown'; + + // Sanitize for HTML + $eventSafe = htmlspecialchars($event, ENT_QUOTES, 'UTF-8'); + $actionSafe = $action ? htmlspecialchars($action, ENT_QUOTES, 'UTF-8') : null; + $repoSafe = htmlspecialchars($repository, ENT_QUOTES, 'UTF-8'); + $senderSafe = htmlspecialchars($sender, ENT_QUOTES, 'UTF-8'); + $dateSafe = htmlspecialchars($metadata['date'], ENT_QUOTES, 'UTF-8'); + $ipSafe = htmlspecialchars($metadata['ip'], ENT_QUOTES, 'UTF-8'); + + // Build event-specific content + $eventContent = ''; + $eventIcon = '🔔'; + + switch ($event) { + case 'push': + $eventIcon = '📤'; + $ref = htmlspecialchars($payload['ref'] ?? 'Unknown', ENT_QUOTES, 'UTF-8'); + $commits = $payload['commits'] ?? []; + $commitCount = count($commits); + + $eventContent = << +
Push Details
+
+
+
Branch
+
$ref
+
+
+
Commits
+
$commitCount
+
+
+
Pusher
+
$senderSafe
+
+
+ +HTML; + + if ($commitCount > 0) { + $eventContent .= '
Commits
'; + foreach (array_slice($commits, 0, 10) as $commit) { + $message = htmlspecialchars($commit['message'] ?? '', ENT_QUOTES, 'UTF-8'); + $author = htmlspecialchars($commit['author']['name'] ?? 'Unknown', ENT_QUOTES, 'UTF-8'); + $sha = htmlspecialchars(substr($commit['id'] ?? '', 0, 7), ENT_QUOTES, 'UTF-8'); + $eventContent .= "
$sha $message by $author
"; + } + $eventContent .= '
'; + } + break; + + case 'pull_request': + $eventIcon = '🔀'; + $pr = $payload['pull_request'] ?? []; + $prNumber = htmlspecialchars($pr['number'] ?? 'N/A', ENT_QUOTES, 'UTF-8'); + $prTitle = htmlspecialchars($pr['title'] ?? 'N/A', ENT_QUOTES, 'UTF-8'); + $prUrl = htmlspecialchars($pr['html_url'] ?? '#', ENT_QUOTES, 'UTF-8'); + $prState = htmlspecialchars($pr['state'] ?? 'N/A', ENT_QUOTES, 'UTF-8'); + $prBase = htmlspecialchars($pr['base']['ref'] ?? 'N/A', ENT_QUOTES, 'UTF-8'); + $prHead = htmlspecialchars($pr['head']['ref'] ?? 'N/A', ENT_QUOTES, 'UTF-8'); + + $eventContent = << +
Pull Request Details
+
+
+
Number
+
#$prNumber
+
+
+
Title
+
$prTitle
+
+
+
State
+
$prState
+
+
+
Branch
+
$prHead → $prBase
+
+
+
URL
+
$prUrl
+
+
+ +HTML; + break; + + case 'issues': + $eventIcon = '📝'; + $issue = $payload['issue'] ?? []; + $issueNumber = htmlspecialchars($issue['number'] ?? 'N/A', ENT_QUOTES, 'UTF-8'); + $issueTitle = htmlspecialchars($issue['title'] ?? 'N/A', ENT_QUOTES, 'UTF-8'); + $issueUrl = htmlspecialchars($issue['html_url'] ?? '#', ENT_QUOTES, 'UTF-8'); + $issueState = htmlspecialchars($issue['state'] ?? 'N/A', ENT_QUOTES, 'UTF-8'); + + $eventContent = << +
Issue Details
+
+
+
Number
+
#$issueNumber
+
+
+
Title
+
$issueTitle
+
+
+
State
+
$issueState
+
+
+
URL
+
$issueUrl
+
+
+ +HTML; + break; + + case 'release': + $eventIcon = '🚀'; + $release = $payload['release'] ?? []; + $tagName = htmlspecialchars($release['tag_name'] ?? 'N/A', ENT_QUOTES, 'UTF-8'); + $releaseName = htmlspecialchars($release['name'] ?? 'N/A', ENT_QUOTES, 'UTF-8'); + $releaseUrl = htmlspecialchars($release['html_url'] ?? '#', ENT_QUOTES, 'UTF-8'); + + $eventContent = << +
Release Details
+
+
+
Tag
+
$tagName
+
+
+
Name
+
$releaseName
+
+
+
URL
+
$releaseUrl
+
+
+ +HTML; + break; + + default: + // Generic event display - render as structured tables + $eventContent = '
Event Details
'; + $eventContent .= renderDataAsTable($payload); + $eventContent .= '
'; + } + + $actionDisplay = $actionSafe ? " ($actionSafe)" : ''; + + $html = << + + + + + GitHub Webhook - $eventSafe + + + +
+
+

$eventIcon GitHub: $eventSafe$actionDisplay

+

$dateSafe

+
+ +
+
📋 Repository Information
+
+
+
Repository
+
$repoSafe
+
+
+
Event
+
$eventSafe
+
+
+
Sender
+
$senderSafe
+
+
+
IP Address
+
$ipSafe
+
+
+
+ + $eventContent + +
+

This GitHub webhook was automatically forwarded to your email address.

+
+
+ + +HTML; + + $subject = "$eventIcon GitHub $eventSafe$actionDisplay - $repoSafe"; + + return [ + 'html' => $html, + 'subject' => $subject + ]; +} // 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"; +// From header sets the sender address to a no-reply address at wh.dixon.cx +$emailHeaders .= "From: no-reply@wh.dixon.cx\r\n"; // Send the email using PHP's built-in mail function // Parameters: recipient, subject, message body, headers