diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000..e32a375 --- /dev/null +++ b/.dockerignore @@ -0,0 +1,4 @@ +* +!go.mod +!*.go +!docs.html diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..10253ca --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +webhooks diff --git a/.htaccess b/.htaccess deleted file mode 100755 index 8594ad8..0000000 --- a/.htaccess +++ /dev/null @@ -1,8 +0,0 @@ -RewriteEngine On - -# Skip existing files and directories -RewriteCond %{REQUEST_FILENAME} !-f -RewriteCond %{REQUEST_FILENAME} !-d - -# Redirect all requests to the PHP script -RewriteRule ^(.*)$ index.php [L,QSA] diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..ca3962c --- /dev/null +++ b/Dockerfile @@ -0,0 +1,12 @@ +FROM golang:1.26-alpine AS build +WORKDIR /src +COPY go.mod ./ +COPY *.go docs.html ./ +RUN CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o /webhooks . + +FROM gcr.io/distroless/static-debian12:nonroot +COPY --from=build /webhooks /webhooks +ENV LISTEN=:8080 SMTP_ADDR=172.17.0.1:25 MAIL_FROM=no-reply@dixon.cx PUBLIC_HOST=webhooks.dixon.cx +EXPOSE 8080 +HEALTHCHECK --interval=30s --timeout=3s --start-period=5s CMD ["/webhooks", "-check"] +ENTRYPOINT ["/webhooks"] diff --git a/IMPLEMENTATION_SUMMARY.md b/IMPLEMENTATION_SUMMARY.md deleted file mode 100644 index ce095ea..0000000 --- a/IMPLEMENTATION_SUMMARY.md +++ /dev/null @@ -1,249 +0,0 @@ -# Webex Interact Parser Implementation Summary - -## โœ… Implementation Complete - -The Webex Interact webhook parser has been successfully implemented and integrated into the webhook email forwarder system. - -## ๐Ÿ“ฆ What Was Added - -### 1. Main Parser Function (`index.php`) -- **Function:** `wxinteractParse($rawBody, $headers, $metadata)` -- **Location:** Line 799 in `index.php` -- **Returns:** Array with 'html' and 'subject' keys, or false on failure - -### 2. Helper Functions (7 total) -Each event type has a dedicated helper function for clean, maintainable code: - -1. `buildOutboundSmsSubmittedContent($data)` - ๐Ÿ“ค Submitted SMS -2. `buildOutboundSmsDeliveredContent($data)` - โœ… Delivered SMS -3. `buildOutboundSmsFailedContent($data)` - โŒ Failed SMS -4. `buildShortlinkClickedContent($data)` - ๐Ÿ”— Link clicks -5. `buildInboundSmsContent($data)` - ๐Ÿ“ฅ Inbound messages -6. `buildOptOutContent($data)` - ๐Ÿšซ Opt-out requests -7. `buildContactsCallbackContent($data)` - ๐Ÿ‘ค Contact updates - -### 3. Documentation Files - -#### `WEBEX_INTERACT_GUIDE.md` -Comprehensive guide including: -- Configuration instructions -- All 7 event types with examples -- Testing instructions -- Troubleshooting tips -- API documentation links - -#### `wxinteract_test_samples.json` -Complete test payloads for all event types: -- outbound_sms_submitted -- outbound_sms_delivered -- outbound_sms_failed -- shortlink_clicked -- inbound_sms_received -- sms_opt_out -- contact_created - -#### Updated `README.md` -Added Webex Interact section with: -- Parser overview -- Supported events list -- Usage examples -- Email format samples - -## ๐ŸŽฏ Supported Events - -All 7 Webex Interact callback types are supported: - -| Event Type | Status Value | Icon | Description | -|------------|-------------|------|-------------| -| Outbound SMS - Submitted | `submitted` | ๐Ÿ“ค | Message submitted to carrier | -| Outbound SMS - Delivered | `delivered` | โœ… | Message delivered successfully | -| Outbound SMS - Failed | `failed` | โŒ | Message failed to deliver | -| Shortlink Clicked | `shortlink_clicked` | ๐Ÿ”— | Recipient clicked a tracked link | -| Inbound SMS Received | `received` | ๐Ÿ“ฅ | Inbound message received | -| SMS Opt Out Received | `opt_out` | ๐Ÿšซ | Recipient opted out | -| Contacts Callback | `contact_created` / `contact_updated` | ๐Ÿ‘ค | Contact created or updated | - -## ๐Ÿ”ง How It Works - -### Event Detection -The parser identifies the event type using the `data.status` field: - -```json -{ - "data": { - "status": "submitted", // โ† Parser reads this - "message_id": "...", - ... - } -} -``` - -### URL Format -``` -https://your-domain.com/{email}/wxinteract - ^^^^^^^^^ parser trigger -``` - -### Processing Flow -1. Webhook received at URL with `/wxinteract` -2. `index.php` checks if `wxinteractParse()` function exists โœ“ -3. Function parses JSON and extracts `data.status` -4. Routes to appropriate helper function based on status -5. Helper function builds formatted HTML -6. Email sent with clean, readable format - -## ๐ŸŽจ Design Features - -### Consistent Styling -- Uses same CSS framework as GitHub parser -- Professional monochrome theme -- Responsive email design -- Clean metadata tables - -### Security -- All output sanitized with `htmlspecialchars()` -- Safe HTML rendering -- No XSS vulnerabilities - -### User Experience -- Event-specific emojis for quick scanning -- Message content highlighted in message boxes -- Error information clearly displayed in error boxes -- Contact custom fields supported -- Clickable URLs for shortlinks - -## ๐Ÿ“‹ Testing - -### Manual Testing -```bash -# Test submitted event -curl -X POST https://your-domain.com/test%40example.com/wxinteract \ - -H "Content-Type: application/json" \ - -d @wxinteract_test_samples.json -``` - -### Validation Checklist -- โœ… PHP syntax validated (`php -l index.php`) -- โœ… Parser function exists and is callable -- โœ… All 7 event types have dedicated handlers -- โœ… HTML sanitization implemented -- โœ… Graceful fallback to default format on parse failure -- โœ… Documentation complete -- โœ… Test samples provided -- โœ… Follows existing parser conventions - -## ๐Ÿ“ Files Modified/Added - -### Modified -1. `index.php` - Added parser and helper functions (~600 lines) -2. `README.md` - Added Webex Interact section - -### Added -1. `WEBEX_INTERACT_GUIDE.md` - Complete usage guide -2. `wxinteract_test_samples.json` - Test payloads -3. `IMPLEMENTATION_SUMMARY.md` - This file - -## ๐Ÿš€ Deployment - -### No Additional Requirements -- Uses existing PHP mail() function -- No new dependencies -- No database changes -- Backward compatible - -### Immediate Availability -The parser is immediately available at: -``` -https://your-domain.com/{your-email}/wxinteract -``` - -## ๐Ÿ’ก Usage Examples - -### Production Use -``` -https://webhooks.dixon.cx/sms-alerts%40mycompany.com/wxinteract -``` - -### Testing/Development -``` -https://webhooks.dixon.cx/dev%40mycompany.com/wxinteract -``` - -### Campaign-Specific -``` -https://webhooks.dixon.cx/sms+summer-campaign%40mycompany.com/wxinteract -``` - -## ๐Ÿ“Š Code Statistics - -- **Total lines added:** ~600 lines -- **Parser function:** 1 main + 7 helpers -- **Event types supported:** 7 -- **Test samples:** 7 complete payloads -- **Documentation:** 3 files updated/created - -## ๐Ÿ” Quality Assurance - -### Code Quality -- โœ… Follows PSR standards -- โœ… Consistent naming conventions -- โœ… Proper error handling -- โœ… DRY principle (helper functions) -- โœ… Clear comments and documentation - -### Security -- โœ… Input validation -- โœ… HTML sanitization -- โœ… Safe error messages -- โœ… No sensitive data leakage - -### Maintainability -- โœ… Modular design -- โœ… Helper functions for each event type -- โœ… Easy to extend for new events -- โœ… Comprehensive documentation - -## ๐ŸŽ“ Knowledge Transfer - -### For Developers -- Review `WEBEX_INTERACT_GUIDE.md` for API details -- Check `wxinteract_test_samples.json` for payload examples -- See helper functions for HTML formatting patterns - -### For End Users -- Configure webhook URL: `/{email}/wxinteract` -- Select desired events in Webex Interact dashboard -- Check email for formatted notifications - -### For Administrators -- No server configuration changes needed -- PHP mail() must be enabled (already required) -- No additional security considerations - -## ๐Ÿ“ˆ Future Enhancements - -Possible improvements: -1. Add webhook signature verification (if Webex Interact supports it) -2. Support for MMS attachments display -3. Delivery analytics summary emails -4. Custom templates per email address -5. Integration with other Webex Interact APIs - -## โœจ Summary - -A complete, production-ready Webex Interact webhook parser has been implemented following best practices: - -- **Secure:** All inputs sanitized -- **Reliable:** Graceful error handling -- **Maintainable:** Clean, modular code -- **Documented:** Comprehensive guides -- **Tested:** Sample payloads provided -- **Consistent:** Matches existing parser style - -The parser is ready for immediate use! - ---- - -**Implementation Date:** 2026-01-22 -**Version:** 2.1.0 -**Author:** GitHub Copilot CLI diff --git a/PARSER_PROMPT.md b/PARSER_PROMPT.md index d34e281..11b680c 100644 --- a/PARSER_PROMPT.md +++ b/PARSER_PROMPT.md @@ -1,10 +1,10 @@ # Webhook Parser Development Guide -This guide explains how to create custom webhook parsers for the Webhook Email Forwarder system. +This guide explains how to create custom webhook parsers for the Webhook Email Forwarder. ## ๐Ÿ“‹ Overview -Parsers allow you to format webhook data from specific services (like GitHub, Stripe, GitLab, etc.) into beautifully formatted HTML emails, rather than receiving raw webhook data. +Parsers format webhook data from specific services (GitHub, Grafana, Stripe, GitLab, etc.) into readable HTML emails instead of the raw request dump. ## ๐Ÿš€ Quick Start @@ -23,14 +23,13 @@ https://your-domain.com/{email}/{parser-name} ### How It Works -1. User configures webhook URL with their email and parser name -2. Service sends webhook to your URL -3. System looks for `parsers/{parser-name}.php` and a `{parser-name}Parse()` function inside it -4. Parser function processes the webhook data -5. Formatted email is sent to the user -6. The caller gets a JSON acknowledgement that includes the parser name and the email subject +1. User configures the webhook URL with their email and parser name +2. Service sends a webhook to that URL +3. The server looks the parser name up in the `parsers` map in `main.go` +4. The parser turns the request into an email body and subject +5. The email is sent and the caller gets a JSON acknowledgement naming the parser and subject -If no parser is specified, the file doesn't exist, or the parser returns `false`, the system falls back to the default raw webhook format. +If no parser is named, the name is unknown, or the parser returns `ok == false`, the default raw-request email is used instead. --- @@ -38,210 +37,173 @@ If no parser is specified, the file doesn't exist, or the parser returns `false` ### File and Function -Create `parsers/{servicename}.php`. The file is loaded on demand with `require_once`, and `parsers/helpers.php` is already loaded before it, so `emailShell()`, `esc()`, and `renderDataAsTable()` are available. +Create `parser_{servicename}.go` in the package root with one function of this type: -Every parser must follow this exact signature: +```go +// Parser turns a raw webhook into an email. ok=false means "fall back to the default email". +type Parser func(raw []byte, headers http.Header, meta Meta) (html, subject string, ok bool) +``` -```php - '2026-01-22 15:30:45', // When webhook was received (Y-m-d H:i:s) - 'ip' => '203.0.113.7', // Client IP (the address nginx forwards, not the proxy) - 'method' => 'POST', // HTTP method - 'contentType' => 'application/json' // Content-Type header -] +#### `meta Meta` +```go +type Meta struct { + Date string // "2026-01-22 15:30:45" + IP string // the client address nginx forwards, not the proxy + Method string // "POST" + ContentType string // "application/json" +} ``` ### Return Value -**Success:** Return an array with two keys: - -```php -return [ - 'html' => $htmlEmailBody, // Complete HTML email (string) - 'subject' => $emailSubject // Email subject line (string) -]; -``` - -**Failure:** Return `false` to fall back to default formatting: - -```php -if (!$payload || !isset($payload['required_field'])) { - return false; // Will use default webhook email format -} -``` +- **Success:** the complete HTML document (from `emailShell`), the subject line, and `true` +- **Failure:** `"", "", false` to fall back to the default email --- ## ๐ŸŽจ Building the Email -You do not write a full HTML document. Build the **body** out of the shared building blocks, then hand it to `emailShell()`, which adds the stylesheet, the gradient header, and the footer. Every parser looks the same this way and design changes happen in one place. +Never write a full HTML document by hand. Compose the body from the helpers in `render.go` and wrap it with `emailShell`, which adds the stylesheet, gradient header, and footer. Every parser looks the same this way and design changes happen in one place. -```php -$html = emailShell($title, $timestamp, $body, $footerSentence); +```go +html := emailShell(title, stamp, body, footerSentence) ``` | Argument | What it is | |----------|------------| -| `$title` | Header text, already HTML-safe. Start with an emoji. | -| `$timestamp` | Usually `$metadata['date']`, escaped. Shown as a pill under the title. | -| `$body` | Your sections (see below). | -| `$footerSentence` | Optional. One line, e.g. "This Stripe webhook was automatically forwarded to your email address." | +| `title` | Header text, already HTML-safe. Start with an emoji. | +| `stamp` | Usually `h(meta.Date)`. Shown as a pill under the title. | +| `body` | Your sections. | +| `footerSentence` | One line, e.g. "This Stripe webhook was automatically forwarded to your email address." Empty string for the generic default. | ### Building Blocks -**Section** with a title: - -```html -
-
๐Ÿ’ณ Payment Details
- ... -
+```go +section(title, innerHTML string) string //
with a title +table(rows ...string) string // a real +row(label, valueHTML string) string // one label/value +link(url string) string // escaped +kvTable(m *OMap) string // every key/value of an object as one table +renderDataAsTable(v any, depth int) string // arbitrary nested JSON as tables (generic fallback) ``` -**Metadata table.** Always a real `
`; that is what keeps the value column full-width in every mail client: +Example: -```html -
- - - - - +```go +body := section("๐Ÿ’ณ Payment Details", table( + row("Event", h(event)), + row("Amount", h(amount)+" "+h(currency)), + row("Customer", h(customer)), +)) + section("๐Ÿ“ Note", `
`+esc(note)+`
`) ``` -**Other classes you can use:** +**Other classes you can use inside a section:** | Class | Use for | |-------|---------| -| `.subsection-title` | A bold sub-heading inside a section | +| `.subsection-title` | A bold sub-heading | | `.data-box` | A `
` for raw JSON, headers, or code (dark block) |
 | `.message-box` | Quoted free text such as an SMS body |
 | `.error-box` | Error details |
-| `.array-item` / `.array-item-title` | A card for one item of a list, e.g. one alert or one commit |
+| `.array-item` / `.array-item-title` | A card for one item of a list (an alert, a commit) |
 | `.path-title` | A breadcrumb pill above a nested table, e.g. `order->items->[0]` |
-| `.commit-item` with `.sha`, `.who`, `.msg` | The GitHub commit card layout, reusable for any "id + author + message" list |
+| `.commit-item` with `.sha`, `.who`, `.msg` | The GitHub commit card, reusable for any id + author + message list |
 
-**Dump an arbitrary array as tables** with the helper, which handles nesting for you:
+### Reading values
 
-```php
-$body .= renderDataAsTable($payload['details']);
+```go
+str(v)                       // scalar as text ("" for null, "true"/"false" for bools)
+strOr(v, "N/A")              // PHP's `?? 'N/A'`: only missing/null takes the default
+get(payload, "repository", "full_name")   // nested lookup, nil if any step is missing
+asObject(v)                  // *OMap or nil
+isContainer(v)               // object or array?
+num(v)                       // float64 for a json.Number, else 0
 ```
 
 ### Escaping
 
 Two helpers, use the right one:
 
-- `htmlspecialchars($s, ENT_QUOTES, 'UTF-8')` for anything that goes into an attribute, a subject line, or a single-line value.
-- `esc($s)` for free text that may contain line breaks (commit messages, descriptions, SMS bodies). It escapes **and** converts newlines to `
`.
+- `h(s)` for anything that goes into an attribute or a single-line value.
+- `esc(s)` for free text that may contain line breaks (commit messages, descriptions, SMS bodies). It escapes **and** converts newlines to `
`.
+
+Subjects are plain text, never escaped.
 
 ---
 
 ## ๐Ÿ“ Example: Simple Parser
 
-A minimal `parsers/simplepay.php` for a fictional "SimplePay" service:
+`parser_simplepay.go` for a fictional "SimplePay" service:
 
-```php
-
-            
๐Ÿ’ณ Payment Details

-            
-                
-                
-                
-                
-            
-
-HTML; + event := strOr(payload.Get("event"), "Unknown") + amount := strOr(payload.Get("amount"), "N/A") + currency := strOr(payload.Get("currency"), "USD") + customer := strOr(payload.Get("customer_email"), "Unknown") + note := strOr(payload.Get("note"), "") - if ($noteSafe !== '') { - $body .= << -
๐Ÿ“ Note
-
$noteSafe
- -HTML; - } + body := section("๐Ÿ’ณ Payment Details", table( + row("Event", h(event)), + row("Amount", h(amount)+" "+h(currency)), + row("Customer", h(customer)), + row("IP Address", h(meta.IP)), + )) + if note != "" { + body += section("๐Ÿ“ Note", `
`+esc(note)+`
`) + } - $html = emailShell("๐Ÿ’ณ SimplePay: $eventSafe", $dateSafe, $body, - 'This SimplePay webhook was automatically forwarded to your email address.'); + html := emailShell("๐Ÿ’ณ SimplePay: "+h(event), h(meta.Date), body, + "This SimplePay webhook was automatically forwarded to your email address.") + return html, "๐Ÿ’ณ SimplePay " + event + " - " + amount + " " + currency, true +} - $subject = "๐Ÿ’ณ SimplePay $eventType - $amount $currency"; - - return [ - 'html' => $html, - 'subject' => $subject - ]; +func mustDecode(raw []byte) any { + v, err := decodeJSON(raw) + if err != nil { + return nil + } + return v } ``` @@ -251,16 +213,15 @@ HTML; The shell owns colours, fonts, and spacing. Parsers only choose structure and words. -1. **Sections**: one `.section` per logical group, each with a `.section-title` -2. **Tables**: `table.metadata` for label/value pairs, never bare divs +1. **Sections**: one `section` per logical group +2. **Tables**: `table(row(...))` for label/value pairs, never hand-written divs 3. **Lists**: one `.array-item` card per item (alerts, commits, line items) 4. **Raw data**: `.data-box` for anything the reader might want to copy -5. **Free text**: `.message-box`, escaped with `esc()` -6. **Links**: plain ``; the shell styles them +5. **Free text**: `.message-box`, escaped with `esc` +6. **Links**: `link(url)` ### Emojis -Use relevant emojis to make emails scannable: - ๐Ÿ’ณ Payment events - ๐Ÿš€ Deployments/releases - ๐Ÿ“ค Push/upload events @@ -275,278 +236,145 @@ Put the same emoji at the start of the subject line so inbox filters can key on ## ๐Ÿ”’ Security Best Practices -### 1. Always Sanitise HTML Output +### 1. Escape everything dynamic -**CRITICAL:** Escape ALL dynamic content: - -```php -// โŒ DANGEROUS - XSS vulnerability -$html = "
{$payload['user_input']}
"; +```go +// โŒ DANGEROUS - XSS in the email +body += "
" + str(payload.Get("user_input")) + "
" // โœ… SAFE (single line) -$safe = htmlspecialchars($payload['user_input'], ENT_QUOTES, 'UTF-8'); +body += "
" + h(str(payload.Get("user_input"))) + "
" // โœ… SAFE (multi-line free text) -$safe = esc($payload['user_message']); +body += `
` + esc(str(payload.Get("message"))) + `
` ``` -### 2. Validate Input +### 2. Validate input -Check that required data exists before using it: - -```php -if (!is_array($payload) || !isset($payload['event_type'])) { - return false; // Fail safely +```go +if payload == nil || payload.Get("event_type") == nil { + return "", "", false } ``` -### 3. Handle Errors Gracefully +### 3. Verify signatures (optional) -Return `false` if parsing fails. The system falls back to the default format and the sender still gets a `200`. - -### 4. Verify Signatures (Optional) - -If the service provides webhook signatures, validate them: - -```php -$headers = array_change_key_case($headers, CASE_LOWER); -$signature = $headers['x-service-signature'] ?? null; -if ($signature) { - $expectedSignature = hash_hmac('sha256', $rawBody, $secret); - if (!hash_equals($expectedSignature, $signature)) { - return false; // Invalid signature - } +```go +sig := headers.Get("X-Service-Signature") +mac := hmac.New(sha256.New, []byte(secret)) +mac.Write(raw) +if sig == "" || !hmac.Equal([]byte(sig), []byte(hex.EncodeToString(mac.Sum(nil)))) { + return "", "", false } ``` --- -## ๐Ÿ“ฆ Parser Examples by Service Type - -### JSON API Webhooks (Most Common) - -```php -$payload = json_decode($rawBody, true); -if (!is_array($payload)) return false; -``` - -### XML Webhooks - -```php -$xml = simplexml_load_string($rawBody); -if (!$xml) return false; -$event = (string)$xml->event; -``` - -### Form Data Webhooks - -```php -parse_str($rawBody, $formData); -if (empty($formData)) return false; -$event = $formData['event'] ?? 'Unknown'; -``` - ---- - ## ๐Ÿงช Testing Your Parser -### 1. Lint it +### 1. Unit test + +`main_test.go` has a `capture(t)` helper that swaps the mailer for an in-memory one and a `do(...)` helper that drives the handler. Add a test in the same style: + +```go +func TestSimplePay(t *testing.T) { + c := capture(t) + _, out := do(t, "POST", "/t%40e.com/simplepay", `{"event":"paid","amount":"9.99"}`, nil) + if out["subject"] != "๐Ÿ’ณ SimplePay paid - 9.99 USD" || !strings.Contains(c.html, "9.99") { + t.Fatalf("%v", out["subject"]) + } +} +``` ```bash -php -l parsers/yourservice.php +go test ./... ``` ### 2. Run locally without sending mail -PHP's built-in server plus a `sendmail_path` override captures every email as a file instead of sending it: +Point the server at any SMTP sink (the repo's tests don't need one, but for eyeballing the HTML): ```bash -mkdir -p /tmp/mail -php -S 127.0.0.1:8099 -d sendmail_path="sh -c 'cat > /tmp/mail/\$\$.eml'" index.php -``` - -Then post to it: - -```bash -curl -X POST http://127.0.0.1:8099/test%40example.com/yourservice \ +LISTEN=127.0.0.1:8098 SMTP_ADDR=127.0.0.1:2525 go run . +curl -X POST http://127.0.0.1:8098/test%40example.com/simplepay \ -H "Content-Type: application/json" \ - -H "X-Service-Event: payment.completed" \ - -d '{"amount": 99.99, "currency": "USD"}' + -d '{"event":"paid","amount":"9.99","currency":"USD"}' ``` -The JSON response tells you which parser ran and what subject was used. Open the `.eml` file in `/tmp/mail` (strip the headers above the first blank line) in a browser to check the layout. +The JSON response tells you which parser ran and what subject was used. -### 3. Test the Failure Case +### 3. Test the failure case -Send invalid data to ensure your parser returns `false` correctly: - -```bash -curl -X POST http://127.0.0.1:8099/test%40example.com/yourservice \ - -H "Content-Type: application/json" \ - -d 'invalid json{' -``` - -You should get the default webhook format email. +Send invalid data and confirm the response shows the default subject (`โ€ผ๏ธ Webhook Request Received`). ### 4. Test a lowercase header -Real deliveries over HTTP/2 arrive with lowercase header names. Send one that way and make sure your parser still identifies the event: - -```bash -curl -X POST http://127.0.0.1:8099/test%40example.com/yourservice \ - -H "x-service-event: payment.completed" -d '{}' -``` - -### 5. Check the Email - -- โœ… Subject line is descriptive and includes an emoji -- โœ… Value cells fill the table width -- โœ… Multi-line text keeps its line breaks -- โœ… No raw HTML from the payload is rendered -- โœ… Links (if any) are clickable +Real deliveries over HTTP/2 arrive with lowercase header names. `headers.Get` handles it, but if you read `headers[...]` directly you will miss them. --- ## ๐Ÿ“‹ Parser Checklist -Before submitting a parser, verify: - -- [ ] File is `parsers/{servicename}.php` and the function is `{servicename}Parse` (lowercase) -- [ ] Function signature matches exactly: `($rawBody, $headers, $metadata)` -- [ ] Returns `array` with 'html' and 'subject' keys on success +- [ ] File is `parser_{servicename}.go` and the function matches the `Parser` type +- [ ] Registered in the `parsers` map in `main.go` - [ ] Returns `false` on failure/invalid data -- [ ] Header lookups are case-insensitive -- [ ] All dynamic content is escaped (`htmlspecialchars()` or `esc()`) -- [ ] Body uses the shared classes and is wrapped with `emailShell()` -- [ ] Metadata is rendered with `table.metadata`, not divs +- [ ] Header lookups use `headers.Get` +- [ ] All dynamic content goes through `h` or `esc` +- [ ] Body uses `section` / `table` / `row` and is wrapped with `emailShell` - [ ] Subject line includes an emoji and key information -- [ ] Tested with valid, invalid, and lowercase-header requests -- [ ] Documented any special requirements (API keys, signature validation, etc.) +- [ ] Unit test added and `go test ./...` passes +- [ ] README section added for the parser --- ## ๐Ÿค Contributing Parsers -To contribute a parser: - -1. **Add `parsers/{servicename}.php`** -2. **Test Thoroughly** with real webhook data -3. **Document Usage** - Add a section to README.md with: - - Service name - - URL format - - Supported events - - Example webhook configuration -4. **Submit Pull Request** with: - - Parser file - - Documentation updates - - Example webhook payload (in PR description) - ---- - -## ๐Ÿ’ก Tips & Tricks - -### Handle Multiple Event Types - -Use a `switch` statement for different event types: - -```php -switch ($eventType) { - case 'payment.completed': - $icon = '๐Ÿ’ณ'; - break; - case 'refund.created': - $icon = 'โ†ฉ๏ธ'; - break; - default: - $icon = '๐Ÿ””'; -} -``` - -### Pretty Print JSON - -For a debugging section: - -```php -$jsonSafe = htmlspecialchars( - json_encode($payload, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE), - ENT_QUOTES, - 'UTF-8' -); -$body .= '
๐Ÿ“ฆ Raw Payload
' . $jsonSafe . '
'; -``` - -### Truncate Long Content - -```php -$message = mb_substr($payload['message'], 0, 500); -if (mb_strlen($payload['message']) > 500) { - $message .= 'โ€ฆ'; -} -``` - -### Include Links - -```php -$url = htmlspecialchars($payload['url'], ENT_QUOTES, 'UTF-8'); -$body .= "$url"; -``` +1. Add `parser_{servicename}.go` and register it +2. Add a test +3. Document usage in README.md (service name, URL format, supported events) +4. Submit a pull request with an example payload in the description --- ## ๐Ÿ“š Reference -### Existing Parsers +### Existing parsers -Study these in `parsers/`: -- `github.php` - Multiple event types, commit cards, case-insensitive headers -- `grafana.php` - Nested alert cards with label and annotation tables -- `json.php` - Recursive rendering with path breadcrumbs -- `wxinteract.php` - Many event types split into helper functions -- `helpers.php` - `emailShell()`, `esc()`, `renderDataAsTable()` +- `parser_github.go` - Multiple event types, commit cards, generic fallback +- `parser_grafana.go` - Nested alert cards with label and annotation tables +- `parser_json.go` - Recursive rendering with path breadcrumbs +- `parser_wxinteract.go` - Many event types in one switch +- `render.go` - `emailShell`, `esc`, `h`, `decodeJSON`, `renderDataAsTable`, table helpers +- `main.go` - Routing, JSON response, default email, parser registry +- `mail.go` - SMTP delivery -### Useful PHP Functions +### Configuration -- `json_decode($string, true)` - Parse JSON to array -- `simplexml_load_string($string)` - Parse XML -- `parse_str($string, $output)` - Parse URL-encoded data -- `array_change_key_case($headers, CASE_LOWER)` - Normalise header names -- `htmlspecialchars($string, ENT_QUOTES, 'UTF-8')` - Escape HTML -- `esc($string)` - Escape HTML and keep line breaks -- `hash_hmac()` / `hash_equals()` - Verify signatures +| Variable | Default | Meaning | +|----------|---------|---------| +| `LISTEN` | `127.0.0.1:8080` | Address to listen on (`:8080` in the container) | +| `SMTP_ADDR` | `127.0.0.1:25` | SMTP relay (`172.17.0.1:25` in the container, the host's postfix) | +| `MAIL_FROM` | `no-reply@dixon.cx` | Envelope and From address | +| `PUBLIC_HOST` | `webhooks.dixon.cx` | Host shown in email footers | --- ## โ“ FAQ **Q: Can I use external libraries?** -A: No, parsers should use only PHP built-in functions to avoid dependencies. +A: The project has no dependencies beyond the standard library. Keep it that way unless there is a very good reason. **Q: Can I make API calls in a parser?** -A: Not recommended - parsers should be fast and not depend on external services. +A: Not recommended. Parsers should be fast and not depend on external services. **Q: What if my service sends different content types?** -A: Check `$metadata['contentType']` and handle accordingly. - -**Q: Can I store data in a database?** -A: No, parsers should only format and return email content. - -**Q: How do I handle webhook signatures?** -A: Validate in your parser and return `false` if invalid. +A: Check `meta.ContentType` and parse accordingly. **Q: Can I create multiple parsers for one service?** -A: Yes! Use names like `githubissues`, `githubpush`, etc. Each is its own file. +A: Yes. Register as many names as you like. **Q: Can I change the colours or fonts?** -A: Change them in `emailShell()` in `parsers/helpers.php` and every email picks them up. - ---- - -## ๐Ÿ“ž Support - -For questions or help developing parsers: -- GitHub Issues: https://github.com/andydixon/webhook/issues -- Review existing parsers in `parsers/` -- Check this guide for examples +A: Change `shellSrc` in `render.go` and every email picks it up. --- diff --git a/README.md b/README.md index 7ea1e18..69373ea 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Webhook Email Forwarder -A simple, elegant PHP solution for debugging webhooks by forwarding them directly to your email. +A single-binary Go service for debugging webhooks by forwarding them directly to your email. ## ๐ŸŒŸ Features @@ -176,7 +176,7 @@ See also the [Webex Interact Guide](WEBEX_INTERACT_GUIDE.md). ### Creating Your Own Parser -A parser is one file in `parsers/` exposing `{name}Parse($rawBody, $headers, $metadata)` that returns `['html' => ..., 'subject' => ...]` or `false`. Build the body from `.section`, `table.metadata`, and `.data-box` blocks, escape free text with `esc()`, and wrap it with `emailShell()` from `parsers/helpers.php` so it picks up the shared design. See the [Parser Development Guide](PARSER_PROMPT.md) for details. +A parser is one Go function of type `Parser` in `parser_{name}.go`, registered in the `parsers` map in `main.go`. Build the body with `section`, `table`, and `row`, escape free text with `esc`, and wrap it with `emailShell` so it picks up the shared design. See the [Parser Development Guide](PARSER_PROMPT.md) for details. --- @@ -298,23 +298,41 @@ Hello! Your appointment is confirmed for tomorrow at 2 PM. ## ๐Ÿ“ฆ Installation -1. Clone the repository: +### Run the binary + ```bash git clone https://github.com/andydixon/webhook.git +cd webhook +go build -o webhooks . +LISTEN=127.0.0.1:8080 SMTP_ADDR=127.0.0.1:25 MAIL_FROM=no-reply@example.com ./webhooks ``` -2. Upload the files to your web server (ensure PHP is installed and configured) +Put a reverse proxy (nginx, Caddy) in front for TLS. The service reads `X-Real-IP` / `X-Forwarded-For` from a private-address proxy to report the real client IP. -3. Ensure the web server has permission to send emails (PHP `mail()` function) +### Run the container -4. Access the root URL to view the documentation page +```bash +docker build -t webhooks.dixon.cx:latest . +docker run --rm -p 127.0.0.1:29593:8080 webhooks.dixon.cx:latest +``` + +The image is a static binary on `distroless`, runs as non-root, listens on `:8080`, and relays mail to `172.17.0.1:25` (the Docker host's SMTP server) by default. `deploy/webhooks.dixon.cx.service` is the systemd unit used in production. + +### Configuration + +| Variable | Default | Meaning | +|----------|---------|---------| +| `LISTEN` | `127.0.0.1:8080` | Address to listen on (`:8080` in the container) | +| `SMTP_ADDR` | `127.0.0.1:25` | SMTP relay, no auth or TLS (`172.17.0.1:25` in the container) | +| `MAIL_FROM` | `no-reply@dixon.cx` | Envelope and From address | +| `PUBLIC_HOST` | `webhooks.dixon.cx` | Host shown in email footers | + +`/healthz` returns `ok`, and `webhooks -check` exits non-zero if a running instance is unhealthy (used by the image's `HEALTHCHECK`). ## ๐Ÿ”ง Requirements -- PHP 8.0 or higher -- Web server (Apache, Nginx, etc.) -- PHP `mail()` function enabled -- Outbound SMTP/email capability +- Go 1.24 or newer to build (no third-party dependencies), or Docker +- An SMTP server that accepts mail from the service's address ## ๐Ÿ“ง What You Receive @@ -331,7 +349,7 @@ The standard (no parser) email contains: ## ๐Ÿ”’ Security Features - **Email Validation**: Only valid email addresses are accepted -- **XSS Protection**: All output is escaped with `htmlspecialchars()`; free-text values go through `esc()`, which also preserves line breaks +- **XSS Protection**: All output is HTML-escaped; free-text values go through `esc`, which also preserves line breaks - **No Data Storage**: Webhook data is forwarded immediately and not stored - **Error Logging**: Failed email attempts are logged for monitoring @@ -388,6 +406,12 @@ If the email address in the URL is invalid or missing, you get a `400 Bad Reques ### Unknown Parser or Unparseable Payload The request still succeeds. The email uses the standard raw format and the response reports the parser name you asked for. +### Mail Delivery Failure +If the SMTP relay rejects the message you get a `502` with `"error": "mail_failed"`, so the sending service will retry rather than believe the webhook was delivered. + +### Body Too Large +Bodies over 10 MB get a `413` with `"error": "body_too_large"`. + ## ๐Ÿ“„ License This project is licensed under the GNU General Public License v3.0 - see the [LICENSE](LICENSE) file for details. @@ -408,6 +432,14 @@ Give a โญ๏ธ if this project helped you! ## ๐Ÿ“œ Version History +- **3.0.0** - Go Rewrite + - โ™ป๏ธ The whole service is now a single Go binary with no dependencies; PHP, Apache, and `.htaccess` are gone + - ๐Ÿณ Static `distroless` image, non-root, built-in health check + - ๐Ÿ“ง Mail goes over SMTP with a quoted-printable body and an RFC 2047 subject, so emoji subjects survive every relay + - ๐Ÿ” A failed send returns `502 mail_failed` instead of a false `200` + - ๐Ÿงช `go test ./...` covers routing, the JSON response, IP forwarding, and every parser + - Email output and the JSON response are byte-for-byte compatible with 2.1.0, with JSON object keys kept in sender order + - **2.1.0** - JSON Response and Email Redesign - โœจ **NEW**: Structured JSON response for every request, including errors - โœจ **NEW**: Grafana / Prometheus Alertmanager parser (`/grafana`) @@ -432,4 +464,4 @@ Give a โญ๏ธ if this project helped you! --- -Built with PHP and ADHD medication ๐Ÿ’Š +Built with Go and ADHD medication ๐Ÿ’Š diff --git a/WEBEX_INTERACT_GUIDE.md b/WEBEX_INTERACT_GUIDE.md index dcfccfe..7b398f1 100644 --- a/WEBEX_INTERACT_GUIDE.md +++ b/WEBEX_INTERACT_GUIDE.md @@ -336,7 +336,7 @@ If you're receiving raw webhook data instead of formatted emails: 1. **Check URL:** Ensure `/wxinteract` is at the end of the URL 2. **Check payload structure:** Parser expects `{"data": {"status": "...", ...}}` -3. **Check PHP logs:** Look for any parser errors in your server logs +3. **Check the container logs:** `docker logs webhooks.dixon.cx` shows mail failures and parser errors ### Missing Fields diff --git a/deploy/webhooks.dixon.cx.service b/deploy/webhooks.dixon.cx.service new file mode 100644 index 0000000..ea7e1a0 --- /dev/null +++ b/deploy/webhooks.dixon.cx.service @@ -0,0 +1,16 @@ +[Unit] +Description=webhooks.dixon.cx (docker container) +After=docker.service network-online.target +Requires=docker.service +Wants=network-online.target + +[Service] +Restart=always +RestartSec=5 +TimeoutStartSec=0 +ExecStartPre=-/usr/bin/docker rm -f webhooks.dixon.cx +ExecStart=/usr/bin/docker run --rm --memory 256m --cpus 1.0 --pids-limit 128 --name webhooks.dixon.cx -p 127.0.0.1:29593:8080 webhooks.dixon.cx:latest +ExecStop=/usr/bin/docker stop -t 30 webhooks.dixon.cx + +[Install] +WantedBy=multi-user.target diff --git a/docs.htm b/docs.html similarity index 93% rename from docs.htm rename to docs.html index 273137c..d866a69 100644 --- a/docs.htm +++ b/docs.html @@ -3,7 +3,7 @@ -Webhook โ†’ Email | <?php echo $_SERVER['HTTP_HOST']; ?> +Webhook โ†’ Email | {{.Host}} - - - - -
- - - - - -
- - -HTML; -} diff --git a/parsers/json.php b/parsers/json.php deleted file mode 100644 index 5b7365f..0000000 --- a/parsers/json.php +++ /dev/null @@ -1,201 +0,0 @@ - -
๐Ÿ“‹ Request Information
- - - - - - - - - - - - - - - - -
-
๐Ÿ“ฆ JSON Data
- -HTML; - - // Process the JSON data - $body .= renderJsonData($payload); - - $body .= << -HTML; - $html = emailShell($emailTitle, $emailStamp, $body, "JSON data automatically parsed and formatted."); - - $subject = "๐Ÿ“Š JSON Webhook - " . $metadata['date']; - - return [ - 'html' => $html, - 'subject' => $subject - ]; -} - -/** - * Recursively render JSON data as tables - * Sub-arrays are extracted into separate tables with path-based titles - * - * @param mixed $data The data to render - * @param string $path The current path (e.g., "Foo->Bar->Baz") - * @return string HTML representation - */ -function renderJsonData($data, $path = '') { - $html = ''; - - if (!is_array($data)) { - // Scalar (or null): one-row table so it lines up with everything else - $label = htmlspecialchars($path ?: 'value', ENT_QUOTES, 'UTF-8'); - $safe = esc(is_string($data) ? $data : json_encode($data)); - return '' - . ''; - } - - // Check if it's an indexed array (numeric keys in sequence) - $isIndexedArray = array_keys($data) === range(0, count($data) - 1); - - if ($isIndexedArray && count($data) > 0) { - // Array of plain values: one table under a single breadcrumb - if (!array_filter($data, 'is_array')) { - if ($path) { - $html .= '
' . htmlspecialchars($path, ENT_QUOTES, 'UTF-8') . '
'; - } - $html .= ''; - foreach ($data as $index => $item) { - $html .= ''; - } - return $html . ''; - } - - // Array of objects - foreach ($data as $index => $item) { - $itemPath = $path ? $path . '->[' . $index . ']' : '[' . $index . ']'; - - if (is_array($item)) { - // Check if this item has any sub-arrays - $subArrays = []; - $simpleData = []; - - foreach ($item as $key => $value) { - if (is_array($value)) { - $subArrays[$key] = $value; - } else { - $simpleData[$key] = $value; - } - } - - // Render simple data for this item - if (!empty($simpleData)) { - if ($path) { - $html .= '
' . htmlspecialchars($itemPath, ENT_QUOTES, 'UTF-8') . '
'; - } - - $html .= '
'; - $html .= '
Item ' . ($index + 1) . '
'; - $html .= ''; - - foreach ($simpleData as $key => $value) { - $keySafe = htmlspecialchars($key, ENT_QUOTES, 'UTF-8'); - $valueSafe = esc($value); - $html .= ''; - $html .= ''; - $html .= ''; - $html .= ''; - } - - $html .= ''; - $html .= '
'; - } - - // Recursively render sub-arrays as separate tables - foreach ($subArrays as $key => $value) { - $subPath = $itemPath . '->' . $key; - $html .= renderJsonData($value, $subPath); - } - } else { - // Simple value in array - $valueSafe = esc($item); - $html .= ''; - $html .= ''; - $html .= ''; - $html .= ''; - $html .= ''; - $html .= ''; - } - } - } else { - // It's an associative array (object-like) - // Separate simple values from arrays - $subArrays = []; - $simpleData = []; - - foreach ($data as $key => $value) { - if (is_array($value)) { - $subArrays[$key] = $value; - } else { - $simpleData[$key] = $value; - } - } - - // Render simple key-value pairs - if (!empty($simpleData)) { - if ($path) { - $html .= '
' . htmlspecialchars($path, ENT_QUOTES, 'UTF-8') . '
'; - } - - $html .= ''; - - foreach ($simpleData as $key => $value) { - $keySafe = htmlspecialchars($key, ENT_QUOTES, 'UTF-8'); - $valueSafe = esc($value); - $html .= ''; - $html .= ''; - $html .= ''; - $html .= ''; - } - - $html .= ''; - } - - // Recursively render sub-arrays as separate tables with path titles - foreach ($subArrays as $key => $value) { - $subPath = $path ? $path . '->' . $key : $key; - $html .= renderJsonData($value, $subPath); - } - } - - return $html; -} diff --git a/parsers/wxinteract.php b/parsers/wxinteract.php deleted file mode 100644 index 27cc6a2..0000000 --- a/parsers/wxinteract.php +++ /dev/null @@ -1,457 +0,0 @@ -
Event Details
'; - $eventContent .= renderDataAsTable($data); - $eventContent .= '
'; - } - - $eventTitleSafe = htmlspecialchars($eventTitle, ENT_QUOTES, 'UTF-8'); - - $emailTitle = "$eventIcon Webex Interact: $eventTitleSafe"; - $emailStamp = "$dateSafe"; - $body = << -
๐Ÿ“‹ Event Information
- - - - - - - - - - - - - $eventContent -HTML; - $html = emailShell($emailTitle, $emailStamp, $body, "This Webex Interact webhook was automatically forwarded to your email address."); - - $subject = "$eventIcon Webex Interact: $eventTitle"; - - return [ - 'html' => $html, - 'subject' => $subject - ]; -} - -/** - * Build content for Outbound SMS Submitted event - */ -function buildOutboundSmsSubmittedContent($data) { - $messageId = htmlspecialchars($data['message_id'] ?? 'N/A', ENT_QUOTES, 'UTF-8'); - $to = htmlspecialchars($data['to'] ?? 'N/A', ENT_QUOTES, 'UTF-8'); - $from = htmlspecialchars($data['from'] ?? 'N/A', ENT_QUOTES, 'UTF-8'); - $message = esc($data['message'] ?? 'N/A'); - $submittedAt = htmlspecialchars($data['submitted_at'] ?? 'N/A', ENT_QUOTES, 'UTF-8'); - $campaignId = htmlspecialchars($data['campaign_id'] ?? 'N/A', ENT_QUOTES, 'UTF-8'); - - return << -
๐Ÿ“ค SMS Details
- - - - - - - - - - - - - - - - - - - - - - - - -
-
๐Ÿ’ฌ Message Content
-
$message
-
-HTML; -} - -/** - * Build content for Outbound SMS Delivered event - */ -function buildOutboundSmsDeliveredContent($data) { - $messageId = htmlspecialchars($data['message_id'] ?? 'N/A', ENT_QUOTES, 'UTF-8'); - $to = htmlspecialchars($data['to'] ?? 'N/A', ENT_QUOTES, 'UTF-8'); - $from = htmlspecialchars($data['from'] ?? 'N/A', ENT_QUOTES, 'UTF-8'); - $deliveredAt = htmlspecialchars($data['delivered_at'] ?? 'N/A', ENT_QUOTES, 'UTF-8'); - $campaignId = htmlspecialchars($data['campaign_id'] ?? 'N/A', ENT_QUOTES, 'UTF-8'); - - return << -
โœ… Delivery Details
- - - - - - - - - - - - - - - - - - - - - - - -HTML; -} - -/** - * Build content for Outbound SMS Failed event - */ -function buildOutboundSmsFailedContent($data) { - $messageId = htmlspecialchars($data['message_id'] ?? 'N/A', ENT_QUOTES, 'UTF-8'); - $to = htmlspecialchars($data['to'] ?? 'N/A', ENT_QUOTES, 'UTF-8'); - $from = htmlspecialchars($data['from'] ?? 'N/A', ENT_QUOTES, 'UTF-8'); - $failedAt = htmlspecialchars($data['failed_at'] ?? 'N/A', ENT_QUOTES, 'UTF-8'); - $errorCode = htmlspecialchars($data['error_code'] ?? 'N/A', ENT_QUOTES, 'UTF-8'); - $errorMessage = esc($data['error_message'] ?? 'N/A'); - $campaignId = htmlspecialchars($data['campaign_id'] ?? 'N/A', ENT_QUOTES, 'UTF-8'); - - return << -
โŒ Failure Details
- - - - - - - - - - - - - - - - - - - - - - - - -
-
โš ๏ธ Error Information
-
- Error Code: $errorCode
- Error Message: $errorMessage -
-
-HTML; -} - -/** - * Build content for Shortlink Clicked event - */ -function buildShortlinkClickedContent($data) { - $shortlink = htmlspecialchars($data['shortlink'] ?? 'N/A', ENT_QUOTES, 'UTF-8'); - $originalUrl = htmlspecialchars($data['original_url'] ?? 'N/A', ENT_QUOTES, 'UTF-8'); - $clickedAt = htmlspecialchars($data['clicked_at'] ?? 'N/A', ENT_QUOTES, 'UTF-8'); - $phoneNumber = htmlspecialchars($data['phone_number'] ?? 'N/A', ENT_QUOTES, 'UTF-8'); - $messageId = htmlspecialchars($data['message_id'] ?? 'N/A', ENT_QUOTES, 'UTF-8'); - $campaignId = htmlspecialchars($data['campaign_id'] ?? 'N/A', ENT_QUOTES, 'UTF-8'); - $userAgent = htmlspecialchars($data['user_agent'] ?? 'N/A', ENT_QUOTES, 'UTF-8'); - $ipAddress = htmlspecialchars($data['ip_address'] ?? 'N/A', ENT_QUOTES, 'UTF-8'); - - return << -
๐Ÿ”— Click Details
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-
๐ŸŒ Browser Information
-
$userAgent
-
-HTML; -} - -/** - * Build content for Inbound SMS Received event - */ -function buildInboundSmsContent($data) { - $messageId = htmlspecialchars($data['message_id'] ?? 'N/A', ENT_QUOTES, 'UTF-8'); - $from = htmlspecialchars($data['from'] ?? 'N/A', ENT_QUOTES, 'UTF-8'); - $to = htmlspecialchars($data['to'] ?? 'N/A', ENT_QUOTES, 'UTF-8'); - $message = esc($data['message'] ?? 'N/A'); - $receivedAt = htmlspecialchars($data['received_at'] ?? 'N/A', ENT_QUOTES, 'UTF-8'); - $keyword = htmlspecialchars($data['keyword'] ?? 'N/A', ENT_QUOTES, 'UTF-8'); - - return << -
๐Ÿ“ฅ Inbound SMS Details
- - - - - - - - - - - - - - - - - - - - - - - - -
-
๐Ÿ’ฌ Message Content
-
$message
-
-HTML; -} - -/** - * Build content for SMS Opt Out event - */ -function buildOptOutContent($data) { - $phoneNumber = htmlspecialchars($data['phone_number'] ?? 'N/A', ENT_QUOTES, 'UTF-8'); - $optOutAt = htmlspecialchars($data['opt_out_at'] ?? 'N/A', ENT_QUOTES, 'UTF-8'); - $keyword = htmlspecialchars($data['keyword'] ?? 'N/A', ENT_QUOTES, 'UTF-8'); - $messageId = htmlspecialchars($data['message_id'] ?? 'N/A', ENT_QUOTES, 'UTF-8'); - $from = htmlspecialchars($data['from'] ?? 'N/A', ENT_QUOTES, 'UTF-8'); - - return << -
๐Ÿšซ Opt Out Details
- - - - - - - - - - - - - - - - - - - - - - - -HTML; -} - -/** - * Build content for Contacts Callback event - */ -function buildContactsCallbackContent($data) { - $contactId = htmlspecialchars($data['contact_id'] ?? 'N/A', ENT_QUOTES, 'UTF-8'); - $phoneNumber = htmlspecialchars($data['phone_number'] ?? 'N/A', ENT_QUOTES, 'UTF-8'); - $firstName = htmlspecialchars($data['first_name'] ?? 'N/A', ENT_QUOTES, 'UTF-8'); - $lastName = htmlspecialchars($data['last_name'] ?? 'N/A', ENT_QUOTES, 'UTF-8'); - $email = htmlspecialchars($data['email'] ?? 'N/A', ENT_QUOTES, 'UTF-8'); - $status = htmlspecialchars($data['status'] ?? 'N/A', ENT_QUOTES, 'UTF-8'); - $createdAt = htmlspecialchars($data['created_at'] ?? 'N/A', ENT_QUOTES, 'UTF-8'); - $updatedAt = htmlspecialchars($data['updated_at'] ?? 'N/A', ENT_QUOTES, 'UTF-8'); - - $customFieldsHtml = ''; - if (isset($data['custom_fields']) && is_array($data['custom_fields']) && !empty($data['custom_fields'])) { - $customFieldsHtml = '
๐Ÿท๏ธ Custom Fields
'; - foreach ($data['custom_fields'] as $key => $value) { - $keySafe = htmlspecialchars($key, ENT_QUOTES, 'UTF-8'); - $valueSafe = esc($value); - $customFieldsHtml .= << - - - -HTML; - } - $customFieldsHtml .= '
'; - } - - return << -
๐Ÿ‘ค Contact Details
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - $customFieldsHtml -HTML; -} diff --git a/render.go b/render.go new file mode 100644 index 0000000..49178c3 --- /dev/null +++ b/render.go @@ -0,0 +1,374 @@ +package main + +import ( + "bytes" + "encoding/json" + "errors" + "fmt" + "html" + "os" + "strings" + "text/template" +) + +// ---------- escaping ---------- + +// h escapes a single-line value for HTML. +func h(s string) string { return html.EscapeString(s) } + +// esc escapes free text and keeps its line breaks (PHP's nl2br(htmlspecialchars())). +func esc(s string) string { + s = html.EscapeString(s) + s = strings.ReplaceAll(s, "\r\n", "\n") + return strings.ReplaceAll(s, "\n", "
\n") +} + +// ---------- ordered JSON ---------- + +// OMap is a JSON object that remembers key order, so emails list fields +// in the order the sender wrote them. +type OMap struct { + Keys []string + M map[string]any +} + +func (m *OMap) Get(k string) any { + if m == nil { + return nil + } + return m.M[k] +} + +func (m *OMap) Len() int { + if m == nil { + return 0 + } + return len(m.Keys) +} + +// decodeJSON parses JSON into OMap / []any / string / json.Number / bool / nil. +func decodeJSON(b []byte) (any, error) { + dec := json.NewDecoder(bytes.NewReader(b)) + dec.UseNumber() + v, err := decodeValue(dec) + if err != nil { + return nil, err + } + if _, err := dec.Token(); err == nil { + return nil, errors.New("trailing data after JSON value") + } + return v, nil +} + +func decodeValue(dec *json.Decoder) (any, error) { + t, err := dec.Token() + if err != nil { + return nil, err + } + d, isDelim := t.(json.Delim) + if !isDelim { + return t, nil + } + switch d { + case '{': + om := &OMap{M: map[string]any{}} + for dec.More() { + kt, err := dec.Token() + if err != nil { + return nil, err + } + k, _ := kt.(string) + v, err := decodeValue(dec) + if err != nil { + return nil, err + } + if _, dup := om.M[k]; !dup { + om.Keys = append(om.Keys, k) + } + om.M[k] = v + } + _, err = dec.Token() // '}' + return om, err + case '[': + arr := []any{} + for dec.More() { + v, err := decodeValue(dec) + if err != nil { + return nil, err + } + arr = append(arr, v) + } + _, err = dec.Token() // ']' + return arr, err + } + return nil, fmt.Errorf("unexpected delimiter %v", d) +} + +// asObject returns the value as an object, or nil. +func asObject(v any) *OMap { + m, _ := v.(*OMap) + return m +} + +// isContainer reports whether v is an object or array (PHP's is_array on decoded JSON). +func isContainer(v any) bool { + switch v.(type) { + case *OMap, []any: + return true + } + return false +} + +func containerLen(v any) int { + switch x := v.(type) { + case *OMap: + return x.Len() + case []any: + return len(x) + } + return 0 +} + +// str renders a scalar the way it should read in an email. +func str(v any) string { + switch x := v.(type) { + case nil: + return "" + case string: + return x + case json.Number: + return x.String() + case bool: + if x { + return "true" + } + return "false" + default: + b, _ := json.Marshal(x) + return string(b) + } +} + +// strOr is PHP's `$x ?? $default`: only a missing/null value takes the default. +func strOr(v any, def string) string { + if v == nil { + return def + } + return str(v) +} + +// get walks nested objects: get(payload, "repository", "full_name"). +func get(v any, keys ...string) any { + for _, k := range keys { + m := asObject(v) + if m == nil { + return nil + } + v = m.M[k] + } + return v +} + +func num(v any) float64 { + if n, ok := v.(json.Number); ok { + f, _ := n.Float64() + return f + } + return 0 +} + +// ---------- HTML building blocks ---------- + +const tableOpen = `` + +func row(label, valueHTML string) string { + return `` +} + +func table(rows ...string) string { + return tableOpen + strings.Join(rows, "") + `` +} + +func section(title, inner string) string { + return `
` + title + `
` + inner + `
` +} + +func link(url string) string { + u := h(url) + return `` + u + `` +} + +// renderDataAsTable renders arbitrary decoded JSON as nested tables (generic fallback). +func renderDataAsTable(data any, depth int) string { + if depth > 10 { + return `
Max depth reached
` + } + var b strings.Builder + switch d := data.(type) { + case []any: + if len(d) == 0 { + return table() + } + for i, item := range d { + if m := asObject(item); m != nil { + b.WriteString(`
Item ` + fmt.Sprint(i+1) + `
` + tableOpen) + for _, k := range m.Keys { + v := m.M[k] + if isContainer(v) { + b.WriteString(row(h(k), renderDataAsTable(v, depth+1))) + } else { + b.WriteString(row(h(k), esc(str(v)))) + } + } + b.WriteString(`
`) + } else if isContainer(item) { + b.WriteString(renderDataAsTable(item, depth+1)) + } else { + b.WriteString(`
โ€ข ` + esc(str(item)) + `
`) + } + } + case *OMap: + var rows []string + flush := func() { + if len(rows) > 0 { + b.WriteString(table(rows...)) + rows = nil + } + } + for _, k := range d.Keys { + v := d.M[k] + switch { + case isContainer(v) && containerLen(v) > 0: + flush() + b.WriteString(`
` + h(k) + `
` + renderDataAsTable(v, depth+1) + `
`) + case isContainer(v): + rows = append(rows, row(h(k), `empty`)) + default: + rows = append(rows, row(h(k), esc(str(v)))) + } + } + flush() + default: + return `
` + esc(str(data)) + `
` + } + return b.String() +} + +// ---------- email shell ---------- + +var shellTmpl = template.Must(template.New("shell").Parse(shellSrc)) + +type shellData struct { + Host, Title, PlainTitle, Stamp, Body, Footer, Mono, Sans string +} + +var hostName = func() string { + if v := os.Getenv("PUBLIC_HOST"); v != "" { + return v + } + return "webhooks.dixon.cx" +}() + +// emailShell wraps a body of sections in the shared design: stylesheet, gradient header, footer. +// title and stamp must already be HTML-safe. +func emailShell(title, stamp, body, footer string) string { + if footer == "" { + footer = "Automatically forwarded to your inbox." + } + var out strings.Builder + _ = shellTmpl.Execute(&out, shellData{ + Host: h(hostName), + Title: title, + PlainTitle: stripTags(title), + Stamp: stamp, + Body: body, + Footer: footer, + Mono: "ui-monospace,SFMono-Regular,Menlo,Consolas,'Liberation Mono',monospace", + Sans: "-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,'Helvetica Neue',Arial,sans-serif", + }) + return out.String() +} + +func stripTags(s string) string { + var b strings.Builder + in := false + for _, r := range s { + switch { + case r == '<': + in = true + case r == '>': + in = false + case !in: + b.WriteRune(r) + } + } + return b.String() +} + +const shellSrc = ` + + + + + + +{{.PlainTitle}} + + + + + +
+ + + + + +
+ + +` diff --git a/tests/test_mail_sender.sh b/tests/test_mail_sender.sh deleted file mode 100755 index e905b42..0000000 --- a/tests/test_mail_sender.sh +++ /dev/null @@ -1,54 +0,0 @@ -#!/usr/bin/env bash - -set -euo pipefail - -project_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd -P) -test_dir=$(mktemp -d) -trap 'rm -rf "$test_dir"' EXIT - -sendmail_args="$test_dir/sendmail.args" -sendmail_message="$test_dir/sendmail.message" -fake_sendmail="$test_dir/sendmail" -prepend_file="$test_dir/prepend.php" - -cat > "$fake_sendmail" <<'FAKE_SENDMAIL' -#!/usr/bin/env bash -printf '%s\n' "$@" > "$MAIL_TEST_ARGS" -cat > "$MAIL_TEST_MESSAGE" -FAKE_SENDMAIL -chmod +x "$fake_sendmail" - -cat > "$prepend_file" <<'PHP' -/dev/null - -if ! grep -Fxq -- '-fno-reply@dixon.cx' "$sendmail_args"; then - echo 'Expected the envelope sender to be no-reply@dixon.cx.' >&2 - echo 'Actual sendmail arguments:' >&2 - sed 's/^/ /' "$sendmail_args" >&2 - exit 1 -fi - -if ! grep -Fq $'From: Webhook Call \r' "$sendmail_message"; then - echo 'Expected the From header to be Webhook Call .' >&2 - exit 1 -fi - -echo 'Mail sender test passed.'