`; that is what keeps the value column full-width in every mail client:
```html
```
**Other classes you can use:**
| Class | Use for |
|-------|---------|
| `.subsection-title` | A bold sub-heading inside a section |
| `.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 |
| `.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 |
**Dump an arbitrary array as tables** with the helper, which handles nesting for you:
```php
$body .= renderDataAsTable($payload['details']);
```
### 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 `
`.
---
## ๐ Example: Simple Parser
A minimal `parsers/simplepay.php` for a fictional "SimplePay" service:
```php
๐ณ Payment Details
HTML;
if ($noteSafe !== '') {
$body .= <<
๐ Note
$noteSafe
HTML;
}
$html = emailShell("๐ณ SimplePay: $eventSafe", $dateSafe, $body,
'This SimplePay webhook was automatically forwarded to your email address.');
$subject = "๐ณ SimplePay $eventType - $amount $currency";
return [
'html' => $html,
'subject' => $subject
];
}
```
---
## ๐จ Style Guidelines
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
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
### Emojis
Use relevant emojis to make emails scannable:
- ๐ณ Payment events
- ๐ Deployments/releases
- ๐ค Push/upload events
- ๐ Merge/pull request events
- โ ๏ธ Errors/warnings
- โ
Success events
- ๐ Notifications
Put the same emoji at the start of the subject line so inbox filters can key on it.
---
## ๐ Security Best Practices
### 1. Always Sanitise HTML Output
**CRITICAL:** Escape ALL dynamic content:
```php
// โ DANGEROUS - XSS vulnerability
$html = "{$payload['user_input']}
";
// โ
SAFE (single line)
$safe = htmlspecialchars($payload['user_input'], ENT_QUOTES, 'UTF-8');
// โ
SAFE (multi-line free text)
$safe = esc($payload['user_message']);
```
### 2. Validate Input
Check that required data exists before using it:
```php
if (!is_array($payload) || !isset($payload['event_type'])) {
return false; // Fail safely
}
```
### 3. Handle Errors Gracefully
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
}
}
```
---
## ๐ฆ 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
```bash
php -l parsers/yourservice.php
```
### 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:
```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 \
-H "Content-Type: application/json" \
-H "X-Service-Event: payment.completed" \
-d '{"amount": 99.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.
### 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.
### 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
---
## ๐ 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
- [ ] 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
- [ ] 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.)
---
## ๐ค 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 . '