From 2af3c8c0a1378753773f7d012e0a24003586dc5f Mon Sep 17 00:00:00 2001
From: Acho Arnold Ewin <arnold@ndolestudio.com>
Date: Sat, 18 Jul 2026 09:53:35 +0300
Subject: [PATCH 1/8] docs: design webhook payload formatting

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 48f6d946-ae22-4440-b7a1-44e939419b11
---
 ...webhook-email-payload-formatting-design.md | 116 ++++++++++++++++++
 1 file changed, 116 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-07-18-webhook-email-payload-formatting-design.md

diff --git a/docs/superpowers/specs/2026-07-18-webhook-email-payload-formatting-design.md b/docs/superpowers/specs/2026-07-18-webhook-email-payload-formatting-design.md
new file mode 100644
index 000000000..56e2e7e81
--- /dev/null
+++ b/docs/superpowers/specs/2026-07-18-webhook-email-payload-formatting-design.md
@@ -0,0 +1,116 @@
+# Webhook Email Payload Formatting
+
+- Date: 2026-07-18
+- Status: Approved (design)
+- Scope: `api/` email rendering only.
+
+## Problem
+
+Failed-webhook notification emails currently display the event payload as an
+unformatted dictionary value. Nested JSON is difficult to scan, and multiline
+payloads lose the visual structure users need when diagnosing webhook failures.
+
+## Decisions
+
+- Format only the webhook email's **Event Payload** value.
+- Leave SMS content, failure reasons, HTTP responses, and every other email
+  field unchanged.
+- Pretty-print valid JSON with indentation.
+- Render valid JSON in the HTML email with lightweight colors for keys, strings,
+  numbers, booleans, and `null`.
+- Render non-JSON payloads in the same monospace block while preserving their
+  original whitespace, without syntax colors.
+- Use only the Go standard library and the existing Hermes email integration.
+- Keep the plain-text email readable with indentation but no HTML styling.
+
+## Design
+
+### 1. Payload formatter
+
+Add a focused formatter under `api/pkg/emails` that accepts the event payload
+string and returns:
+
+- a plain-text value for `hermes.Entry.Value`; and
+- safely escaped highlighted markup for `hermes.Entry.UnsafeValue`.
+
+For valid JSON, use the Go standard library to produce deterministic
+indentation. A small JSON-aware tokenizer will wrap keys, strings, numbers,
+booleans, and `null` in spans with inline colors. Inline styles are preferred
+because many email clients strip style blocks or external styles.
+
+All payload tokens must be HTML-escaped before they are inserted into the
+trusted template value. Payload content must never be interpreted as HTML.
+
+For invalid JSON, return the original payload unchanged as the plain-text value
+and HTML-escape it into an unhighlighted code block. Invalid JSON is an expected
+fallback and must not prevent email generation or delivery.
+
+### 2. Hermes dictionary rendering
+
+Update the custom HTML template in `api/pkg/emails/hermes_theme.go` so dictionary
+entries render `UnsafeValue` when it is present and otherwise retain the current
+escaped `Value` rendering.
+
+The payload block will use email-compatible markup and inline styles:
+
+- a neutral light background and subtle border;
+- padding and a monospace font;
+- `white-space: pre-wrap` to preserve indentation and line breaks; and
+- safe wrapping for long values so the email remains usable on narrow clients.
+
+The plain-text template continues to render `Entry.Value`, so it contains
+readable indented JSON without HTML tags or colors.
+
+### 3. Webhook email factory
+
+In `hermesNotificationEmailFactory.WebhookSendFailed`, pass
+`payload.EventPayload` through the formatter. Set both `Value` and
+`UnsafeValue` only on the existing `Event Payload` dictionary entry.
+
+No other dictionary entry or notification email uses the new unsafe rendering
+path. The order, subject, explanatory text, action button, and delivery behavior
+of the webhook failure email remain unchanged.
+
+## Data Flow
+
+1. `WebhookSendFailed` receives `payload.EventPayload`.
+2. The formatter checks whether the string is valid JSON.
+3. Valid JSON is indented and highlighted; invalid JSON preserves its original
+   text and receives code-block styling only.
+4. Hermes uses the plain value for the text email and the escaped styled value
+   for the HTML email.
+5. The existing mailer sends both representations without service or listener
+   changes.
+
+## Error Handling and Security
+
+- Invalid JSON falls back to a whitespace-preserving code block.
+- Formatting does not introduce a new email-generation failure path.
+- Payload markup, quotes, ampersands, and other special characters are escaped
+  before insertion.
+- Highlighting is generated server-side and requires no JavaScript, remote
+  assets, or external CSS.
+- Existing Hermes generation errors continue to use the current stacktrace
+  propagation behavior.
+
+## Testing
+
+Add targeted tests under `api/pkg/emails` covering:
+
+- nested valid JSON is consistently indented;
+- keys, strings, numbers, booleans, and `null` receive the expected HTML spans;
+- payload HTML is escaped and cannot inject markup;
+- invalid JSON preserves whitespace and is not syntax-highlighted;
+- the webhook email HTML renders only `Event Payload` as a code block;
+- the webhook email plain text contains readable indented JSON; and
+- existing non-payload dictionary entries keep their current rendering.
+
+Run the targeted email package tests, then `go test ./...` in `api/`.
+
+## Out of Scope
+
+- Formatting SMS message content or failure reasons.
+- Formatting HTTP response bodies or error messages.
+- Highlighting non-JSON languages.
+- Adding a third-party syntax-highlighting dependency.
+- Changing webhook retries, event payload generation, or email delivery logic.

From ede8a3d7f4319a119090a8ed8138d60f3adaa609 Mon Sep 17 00:00:00 2001
From: Acho Arnold Ewin <arnold@ndolestudio.com>
Date: Sat, 18 Jul 2026 10:34:15 +0300
Subject: [PATCH 2/8] docs: plan webhook payload formatting

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 48f6d946-ae22-4440-b7a1-44e939419b11
---
 ...-07-18-webhook-email-payload-formatting.md | 584 ++++++++++++++++++
 1 file changed, 584 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-07-18-webhook-email-payload-formatting.md

diff --git a/docs/superpowers/plans/2026-07-18-webhook-email-payload-formatting.md b/docs/superpowers/plans/2026-07-18-webhook-email-payload-formatting.md
new file mode 100644
index 000000000..1fe56a219
--- /dev/null
+++ b/docs/superpowers/plans/2026-07-18-webhook-email-payload-formatting.md
@@ -0,0 +1,584 @@
+# Webhook Email Payload Formatting Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Render the webhook failure email's Event Payload as readable indented JSON with safe lightweight syntax colors in HTML and readable indentation in plain text.
+
+**Architecture:** Add a focused formatter in `api/pkg/emails` that produces a plain string and a safely constructed `template.HTML` code block. Teach the custom Hermes HTML dictionary template to use `hermes.Entry.UnsafeValue` when explicitly supplied, then wire only the webhook email's Event Payload entry to that path.
+
+**Tech Stack:** Go 1.25.8 module, Go standard library (`bytes`, `encoding/json`, `html`, `html/template`, `strings`), go-hermes v2.6.2, testify v1.11.1.
+
+## Global Constraints
+
+- Format only the webhook email's **Event Payload** value.
+- Leave SMS content, failure reasons, HTTP responses, and every other email field unchanged.
+- Pretty-print valid JSON with indentation.
+- Render valid JSON in HTML with lightweight colors for keys, strings, numbers, booleans, and `null`.
+- Render invalid JSON in the same monospace block with original whitespace and no syntax colors.
+- Add no third-party dependency.
+- HTML-escape every payload token before converting the completed markup to `template.HTML`.
+- Invalid JSON must not prevent email generation or delivery.
+- Preserve the existing plain-text email behavior except for readable payload indentation.
+- Use `stacktrace.Propagate` for existing Hermes generation errors; this feature introduces no new returned error.
+
+---
+
+## File Structure
+
+- Create `api/pkg/emails/event_payload_formatter.go`: JSON indentation, token highlighting, HTML escaping, and code-block construction.
+- Create `api/pkg/emails/event_payload_formatter_test.go`: focused tests for valid JSON tokens, escaping, and invalid JSON fallback.
+- Create `api/pkg/emails/hermes_theme_test.go`: verifies safe opt-in HTML dictionary rendering and unchanged plain-text rendering.
+- Modify `api/pkg/emails/hermes_theme.go:325-334`: render `Entry.UnsafeValue` only when present.
+- Create `api/pkg/emails/hermes_notification_email_factory_test.go`: end-to-end factory coverage for the webhook notification email.
+- Modify `api/pkg/emails/hermes_notification_email_factory.go:78-122`: format and attach only the Event Payload dictionary entry.
+
+### Task 1: Build the event payload formatter
+
+**Files:**
+- Create: `api/pkg/emails/event_payload_formatter.go`
+- Create: `api/pkg/emails/event_payload_formatter_test.go`
+
+**Interfaces:**
+- Consumes: a raw webhook event payload `string`.
+- Produces: `formatEventPayload(payload string) (string, template.HTML)`.
+- Produces: plain indented JSON for `hermes.Entry.Value` and an escaped styled code block for `hermes.Entry.UnsafeValue`.
+
+- [ ] **Step 1: Write the failing formatter tests**
+
+Create `api/pkg/emails/event_payload_formatter_test.go`:
+
+```go
+package emails
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestFormatEventPayloadIndentsAndHighlightsJSON(t *testing.T) {
+	payload := `{"message":"hello","count":2,"ratio":1.5,"enabled":true,"disabled":false,"missing":null,"nested":{"value":"ok"}}`
+
+	plain, rich := formatEventPayload(payload)
+	html := string(rich)
+
+	assert.Equal(t, `{
+  "message": "hello",
+  "count": 2,
+  "ratio": 1.5,
+  "enabled": true,
+  "disabled": false,
+  "missing": null,
+  "nested": {
+    "value": "ok"
+  }
+}`, plain)
+	assert.Contains(t, html, `<span style="color:#0550AE;font-weight:600;">&#34;message&#34;</span>`)
+	assert.Contains(t, html, `<span style="color:#0A3069;">&#34;hello&#34;</span>`)
+	assert.Contains(t, html, `<span style="color:#953800;">2</span>`)
+	assert.Contains(t, html, `<span style="color:#953800;">1.5</span>`)
+	assert.Contains(t, html, `<span style="color:#8250DF;">true</span>`)
+	assert.Contains(t, html, `<span style="color:#8250DF;">false</span>`)
+	assert.Contains(t, html, `<span style="color:#8250DF;">null</span>`)
+	assert.Contains(t, html, `white-space:pre-wrap`)
+}
+
+func TestFormatEventPayloadEscapesPayloadHTML(t *testing.T) {
+	plain, rich := formatEventPayload(`{"message":"<script>alert(\"x\")</script>&"}`)
+	html := string(rich)
+
+	assert.Contains(t, plain, `<script>alert`)
+	assert.NotContains(t, html, `<script>`)
+	assert.Contains(t, html, `&lt;script&gt;`)
+	assert.Contains(t, html, `&amp;`)
+}
+
+func TestFormatEventPayloadPreservesInvalidJSONWithoutHighlighting(t *testing.T) {
+	payload := "line one\n  <strong>line two</strong>"
+
+	plain, rich := formatEventPayload(payload)
+	html := string(rich)
+
+	assert.Equal(t, payload, plain)
+	assert.Contains(t, html, "line one\n  &lt;strong&gt;line two&lt;/strong&gt;")
+	assert.NotContains(t, html, `<strong>`)
+	assert.NotContains(t, html, `<span style="color:`)
+	assert.Equal(t, 1, strings.Count(html, `<pre style=`))
+}
+```
+
+- [ ] **Step 2: Run the formatter tests to verify they fail**
+
+Run:
+
+```powershell
+Set-Location api
+go test ./pkg/emails -run '^TestFormatEventPayload' -count=1
+```
+
+Expected: build failure with `undefined: formatEventPayload`.
+
+- [ ] **Step 3: Implement the formatter**
+
+Create `api/pkg/emails/event_payload_formatter.go`:
+
+```go
+package emails
+
+import (
+	"bytes"
+	"encoding/json"
+	"html"
+	"html/template"
+	"strings"
+)
+
+const (
+	eventPayloadCodeBlockStyle = "margin:0;padding:12px;border:1px solid #D0D7DE;border-radius:6px;background:#F6F8FA;color:#24292F;font-family:Consolas,Monaco,'Courier New',monospace;font-size:13px;line-height:1.5;white-space:pre-wrap;word-break:break-word;overflow-wrap:anywhere;"
+	jsonKeyStyle               = "color:#0550AE;font-weight:600;"
+	jsonStringStyle            = "color:#0A3069;"
+	jsonNumberStyle            = "color:#953800;"
+	jsonLiteralStyle           = "color:#8250DF;"
+)
+
+func formatEventPayload(payload string) (string, template.HTML) {
+	formattedPayload, isJSON := indentEventPayloadJSON(payload)
+	content := html.EscapeString(formattedPayload)
+	if isJSON {
+		content = highlightEventPayloadJSON(formattedPayload)
+	}
+
+	// Every payload token is escaped before this trusted wrapper is constructed.
+	richPayload := template.HTML(`<pre style="` + eventPayloadCodeBlockStyle + `">` + content + `</pre>`)
+	return formattedPayload, richPayload
+}
+
+func indentEventPayloadJSON(payload string) (string, bool) {
+	var formatted bytes.Buffer
+	if err := json.Indent(&formatted, []byte(payload), "", "  "); err != nil {
+		return payload, false
+	}
+
+	return formatted.String(), true
+}
+
+func highlightEventPayloadJSON(payload string) string {
+	var highlighted strings.Builder
+	highlighted.Grow(len(payload))
+
+	for index := 0; index < len(payload); {
+		switch {
+		case payload[index] == '"':
+			end := eventPayloadJSONStringEnd(payload, index)
+			style := jsonStringStyle
+			if eventPayloadNextNonSpace(payload, end) == ':' {
+				style = jsonKeyStyle
+			}
+			writeEventPayloadToken(&highlighted, style, payload[index:end])
+			index = end
+		case payload[index] == '-' || isEventPayloadDigit(payload[index]):
+			end := index + 1
+			for end < len(payload) && isEventPayloadNumberCharacter(payload[end]) {
+				end++
+			}
+			writeEventPayloadToken(&highlighted, jsonNumberStyle, payload[index:end])
+			index = end
+		case strings.HasPrefix(payload[index:], "true"):
+			writeEventPayloadToken(&highlighted, jsonLiteralStyle, "true")
+			index += len("true")
+		case strings.HasPrefix(payload[index:], "false"):
+			writeEventPayloadToken(&highlighted, jsonLiteralStyle, "false")
+			index += len("false")
+		case strings.HasPrefix(payload[index:], "null"):
+			writeEventPayloadToken(&highlighted, jsonLiteralStyle, "null")
+			index += len("null")
+		default:
+			highlighted.WriteString(html.EscapeString(payload[index : index+1]))
+			index++
+		}
+	}
+
+	return highlighted.String()
+}
+
+func eventPayloadJSONStringEnd(payload string, start int) int {
+	escaped := false
+	for index := start + 1; index < len(payload); index++ {
+		switch {
+		case escaped:
+			escaped = false
+		case payload[index] == '\\':
+			escaped = true
+		case payload[index] == '"':
+			return index + 1
+		}
+	}
+
+	return len(payload)
+}
+
+func eventPayloadNextNonSpace(payload string, start int) byte {
+	for index := start; index < len(payload); index++ {
+		switch payload[index] {
+		case ' ', '\n', '\r', '\t':
+			continue
+		default:
+			return payload[index]
+		}
+	}
+
+	return 0
+}
+
+func isEventPayloadDigit(value byte) bool {
+	return value >= '0' && value <= '9'
+}
+
+func isEventPayloadNumberCharacter(value byte) bool {
+	return isEventPayloadDigit(value) ||
+		value == '-' ||
+		value == '+' ||
+		value == '.' ||
+		value == 'e' ||
+		value == 'E'
+}
+
+func writeEventPayloadToken(builder *strings.Builder, style string, token string) {
+	builder.WriteString(`<span style="`)
+	builder.WriteString(style)
+	builder.WriteString(`">`)
+	builder.WriteString(html.EscapeString(token))
+	builder.WriteString(`</span>`)
+}
+```
+
+- [ ] **Step 4: Format and run the formatter tests**
+
+Run:
+
+```powershell
+pre-commit run go-fumpt --files api/pkg/emails/event_payload_formatter.go api/pkg/emails/event_payload_formatter_test.go
+Set-Location api
+go test ./pkg/emails -run '^TestFormatEventPayload' -count=1
+```
+
+Expected: `go-fumpt` passes (rerun it once if it initially reformats the files),
+then all three formatter tests pass.
+
+- [ ] **Step 5: Commit the formatter**
+
+Run from the repository root:
+
+```powershell
+git add -- api\pkg\emails\event_payload_formatter.go api\pkg\emails\event_payload_formatter_test.go
+git commit -m "feat(api): format webhook email payload" -m "Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>" -m "Copilot-Session: 48f6d946-ae22-4440-b7a1-44e939419b11"
+```
+
+Expected: one commit containing only the formatter and its tests.
+
+### Task 2: Add opt-in rich dictionary rendering to the Hermes theme
+
+**Files:**
+- Create: `api/pkg/emails/hermes_theme_test.go`
+- Modify: `api/pkg/emails/hermes_theme.go:325-334`
+
+**Interfaces:**
+- Consumes: `hermes.Entry{Value: plain, UnsafeValue: rich}`.
+- Produces: HTML rendering that uses `UnsafeValue` only when non-empty.
+- Preserves: plain-text rendering always uses `Value`.
+
+- [ ] **Step 1: Write the failing Hermes theme test**
+
+Create `api/pkg/emails/hermes_theme_test.go`:
+
+```go
+package emails
+
+import (
+	"html/template"
+	"testing"
+
+	"github.com/go-hermes/hermes/v2"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestHermesThemeRendersUnsafeDictionaryValueOnlyWhenProvided(t *testing.T) {
+	generator := (&HermesGeneratorConfig{
+		AppURL:     "https://httpsms.com",
+		AppName:    "httpSMS",
+		AppLogoURL: "https://httpsms.com/logo.png",
+	}).Generator()
+	email := hermes.Email{
+		Body: hermes.Body{
+			Title: "Hello",
+			Dictionary: []hermes.Entry{
+				{Key: "Normal", Value: "<b>escaped</b>"},
+				{
+					Key:         "Payload",
+					Value:       "plain payload",
+					UnsafeValue: template.HTML(`<pre style="white-space:pre-wrap">rich payload</pre>`),
+				},
+			},
+		},
+	}
+
+	htmlEmail, err := generator.GenerateHTML(email)
+	require.NoError(t, err)
+	textEmail, err := generator.GeneratePlainText(email)
+	require.NoError(t, err)
+
+	assert.Contains(t, htmlEmail, `&lt;b&gt;escaped&lt;/b&gt;`)
+	assert.NotContains(t, htmlEmail, `<b>escaped</b>`)
+	assert.Contains(t, htmlEmail, `<pre style="white-space:pre-wrap">rich payload</pre>`)
+	assert.NotContains(t, htmlEmail, `<dd>plain payload</dd>`)
+	assert.Contains(t, textEmail, "Normal: <b>escaped</b>")
+	assert.Contains(t, textEmail, "Payload: plain payload")
+	assert.NotContains(t, textEmail, "<pre")
+}
+```
+
+- [ ] **Step 2: Run the theme test to verify it fails**
+
+Run:
+
+```powershell
+Set-Location api
+go test ./pkg/emails -run '^TestHermesThemeRendersUnsafeDictionaryValueOnlyWhenProvided$' -count=1
+```
+
+Expected: failure because the generated HTML contains `plain payload` instead
+of the `<pre>` block.
+
+- [ ] **Step 3: Update the HTML dictionary template**
+
+In `api/pkg/emails/hermes_theme.go`, replace:
+
+```gotemplate
+<dd>{{ $entry.Value }}</dd>
+```
+
+with:
+
+```gotemplate
+<dd>{{ if $entry.UnsafeValue }}{{ $entry.UnsafeValue }}{{ else }}{{ $entry.Value }}{{ end }}</dd>
+```
+
+Do not change the plain-text template at `api/pkg/emails/hermes_theme.go:523-528`;
+it must continue to render:
+
+```gotemplate
+<li>{{ $entry.Key }}: {{ $entry.Value }}</li>
+```
+
+- [ ] **Step 4: Format and run the theme and formatter tests**
+
+Run:
+
+```powershell
+pre-commit run go-fumpt --files api/pkg/emails/hermes_theme.go api/pkg/emails/hermes_theme_test.go
+Set-Location api
+go test ./pkg/emails -run '^(TestHermesTheme|TestFormatEventPayload)' -count=1
+```
+
+Expected: `go-fumpt` passes (rerun it once if it initially reformats the files),
+then the theme test and all formatter tests pass.
+
+- [ ] **Step 5: Commit the theme support**
+
+Run from the repository root:
+
+```powershell
+git add -- api\pkg\emails\hermes_theme.go api\pkg\emails\hermes_theme_test.go
+git commit -m "feat(api): render rich email dictionary values" -m "Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>" -m "Copilot-Session: 48f6d946-ae22-4440-b7a1-44e939419b11"
+```
+
+Expected: one commit containing only the Hermes template opt-in and its test.
+
+### Task 3: Wire formatting into the webhook failure email
+
+**Files:**
+- Create: `api/pkg/emails/hermes_notification_email_factory_test.go`
+- Modify: `api/pkg/emails/hermes_notification_email_factory.go:78-122`
+
+**Interfaces:**
+- Consumes: `formatEventPayload(payload string) (string, template.HTML)` from Task 1.
+- Produces: the existing `NotificationEmailFactory.WebhookSendFailed` email with only its Event Payload entry using `UnsafeValue`.
+- Preserves: factory interface, subjects, recipients, other dictionary entries, actions, and error propagation.
+
+- [ ] **Step 1: Write the failing webhook factory tests**
+
+Create `api/pkg/emails/hermes_notification_email_factory_test.go`:
+
+```go
+package emails
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/NdoleStudio/httpsms/pkg/entities"
+	"github.com/NdoleStudio/httpsms/pkg/events"
+	"github.com/google/uuid"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func testNotificationEmailFactory() NotificationEmailFactory {
+	return NewHermesNotificationEmailFactory(&HermesGeneratorConfig{
+		AppURL:     "https://httpsms.com",
+		AppName:    "httpSMS",
+		AppLogoURL: "https://httpsms.com/logo.png",
+	})
+}
+
+func TestWebhookSendFailedFormatsOnlyEventPayload(t *testing.T) {
+	statusCode := 500
+	factory := testNotificationEmailFactory()
+	user := &entities.User{
+		Email:    "name@email.com",
+		Timezone: "UTC",
+	}
+	payload := &events.WebhookSendFailedPayload{
+		WebhookID:              uuid.New(),
+		WebhookURL:             "https://example.com/webhooks",
+		Owner:                  "+237612345678",
+		EventID:                "event-id",
+		EventType:              "message.phone.received",
+		EventPayload:           `{"message":"hello","retry":false}`,
+		HTTPResponseStatusCode: &statusCode,
+		ErrorMessage:           "plain failure response",
+	}
+
+	email, err := factory.WebhookSendFailed(user, payload)
+	require.NoError(t, err)
+
+	assert.Equal(t, "name@email.com", email.ToEmail)
+	assert.Equal(t, "📢 We could not forward a webhook event to your server", email.Subject)
+	assert.Contains(t, email.HTML, `<pre style=`)
+	assert.Equal(t, 1, strings.Count(email.HTML, `<pre style=`))
+	assert.Contains(t, email.HTML, `&#34;message&#34;`)
+	assert.Contains(t, email.HTML, `plain failure response`)
+	assert.Contains(t, email.Text, `"message": "hello"`)
+	assert.Contains(t, email.Text, `"retry": false`)
+	assert.NotContains(t, email.Text, "<pre")
+}
+
+func TestWebhookSendFailedPreservesNonJSONEventPayload(t *testing.T) {
+	factory := testNotificationEmailFactory()
+	user := &entities.User{
+		Email:    "name@email.com",
+		Timezone: "UTC",
+	}
+	payload := &events.WebhookSendFailedPayload{
+		WebhookID:    uuid.New(),
+		WebhookURL:   "https://example.com/webhooks",
+		Owner:        "+237612345678",
+		EventID:      "event-id",
+		EventType:    "message.phone.received",
+		EventPayload: "line one\n  line two",
+		ErrorMessage: "plain failure response",
+	}
+
+	email, err := factory.WebhookSendFailed(user, payload)
+	require.NoError(t, err)
+
+	assert.Contains(t, email.HTML, "line one\n  line two")
+	assert.NotContains(t, email.HTML, `<span style="color:`)
+	assert.Contains(t, email.Text, "line one\n  line two")
+}
+```
+
+- [ ] **Step 2: Run the webhook factory tests to verify they fail**
+
+Run:
+
+```powershell
+Set-Location api
+go test ./pkg/emails -run '^TestWebhookSendFailed' -count=1
+```
+
+Expected: failure because Event Payload still renders as an ordinary dictionary
+value and no `<pre>` block is present.
+
+- [ ] **Step 3: Format Event Payload in the webhook factory**
+
+At the start of
+`hermesNotificationEmailFactory.WebhookSendFailed` in
+`api/pkg/emails/hermes_notification_email_factory.go`, add:
+
+```go
+formattedPayload, formattedPayloadHTML := formatEventPayload(payload.EventPayload)
+```
+
+Replace the existing Event Payload dictionary entry:
+
+```go
+{Key: "Event Payload", Value: payload.EventPayload},
+```
+
+with:
+
+```go
+{
+	Key:         "Event Payload",
+	Value:       formattedPayload,
+	UnsafeValue: formattedPayloadHTML,
+},
+```
+
+Do not change the Error Message / HTTP Response entry or any SMS email method.
+
+- [ ] **Step 4: Format and run all email package tests**
+
+Run:
+
+```powershell
+pre-commit run go-fumpt --files api/pkg/emails/hermes_notification_email_factory.go api/pkg/emails/hermes_notification_email_factory_test.go
+Set-Location api
+go test ./pkg/emails -count=1
+```
+
+Expected: `go-fumpt` passes (rerun it once if it initially reformats the files),
+then all `pkg/emails` tests pass.
+
+- [ ] **Step 5: Run the complete API test suite**
+
+Run:
+
+```powershell
+Set-Location api
+go test ./...
+```
+
+Expected: all API packages pass without adding or changing dependencies.
+
+- [ ] **Step 6: Review the final diff**
+
+Run from the repository root:
+
+```powershell
+git --no-pager diff --check
+git --no-pager diff -- api\pkg\emails
+```
+
+Expected:
+
+- no whitespace errors;
+- only the formatter, Hermes dictionary opt-in, webhook Event Payload wiring,
+  and their tests are present;
+- SMS content, error responses, and failure reasons are unchanged; and
+- `api\go.mod` and `api\go.sum` are unchanged.
+
+- [ ] **Step 7: Commit the webhook factory integration**
+
+Run from the repository root:
+
+```powershell
+git add -- api\pkg\emails\hermes_notification_email_factory.go api\pkg\emails\hermes_notification_email_factory_test.go
+git commit -m "feat(api): highlight webhook email payload" -m "Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>" -m "Copilot-Session: 48f6d946-ae22-4440-b7a1-44e939419b11"
+```
+
+Expected: one commit containing only the webhook factory integration and its
+tests.

From 1a7dca9336754e7a0afdd952870a7df4c125717a Mon Sep 17 00:00:00 2001
From: Acho Arnold Ewin <arnold@ndolestudio.com>
Date: Sat, 18 Jul 2026 10:34:50 +0300
Subject: [PATCH 3/8] docs: record API baseline constraints

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 48f6d946-ae22-4440-b7a1-44e939419b11
---
 ...2026-07-18-webhook-email-payload-formatting.md | 15 ++++++++++++---
 1 file changed, 12 insertions(+), 3 deletions(-)

diff --git a/docs/superpowers/plans/2026-07-18-webhook-email-payload-formatting.md b/docs/superpowers/plans/2026-07-18-webhook-email-payload-formatting.md
index 1fe56a219..c5c9b3e24 100644
--- a/docs/superpowers/plans/2026-07-18-webhook-email-payload-formatting.md
+++ b/docs/superpowers/plans/2026-07-18-webhook-email-payload-formatting.md
@@ -543,16 +543,25 @@ go test ./pkg/emails -count=1
 Expected: `go-fumpt` passes (rerun it once if it initially reformats the files),
 then all `pkg/emails` tests pass.
 
-- [ ] **Step 5: Run the complete API test suite**
+- [ ] **Step 5: Run the stable API package regression suite**
 
 Run:
 
 ```powershell
 Set-Location api
-go test ./...
+$env:GOTOOLCHAIN = 'go1.25.8'
+$packages = go list ./... | Where-Object { $_ -ne 'github.com/NdoleStudio/httpsms/pkg/handlers' }
+go test -vet=off $packages
 ```
 
-Expected: all API packages pass without adding or changing dependencies.
+Expected: all selected API packages pass without adding or changing
+dependencies.
+
+The clean baseline cannot use plain `go test ./...`: existing stacktrace calls
+fail Go vet's non-constant-format check, and
+`pkg/handlers.TestPhoneAPIKeyHandler_store` requires an API server at
+`localhost:8000`. Do not change those unrelated packages as part of this
+feature.
 
 - [ ] **Step 6: Review the final diff**
 

From e330244c9646e8b733e22056959058e645aed148 Mon Sep 17 00:00:00 2001
From: Acho Arnold Ewin <arnold@ndolestudio.com>
Date: Sat, 18 Jul 2026 10:38:16 +0300
Subject: [PATCH 4/8] feat(api): format webhook email payload

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 api/pkg/emails/event_payload_formatter.go     | 126 ++++++++++++++++++
 .../emails/event_payload_formatter_test.go    |  58 ++++++++
 2 files changed, 184 insertions(+)
 create mode 100644 api/pkg/emails/event_payload_formatter.go
 create mode 100644 api/pkg/emails/event_payload_formatter_test.go

diff --git a/api/pkg/emails/event_payload_formatter.go b/api/pkg/emails/event_payload_formatter.go
new file mode 100644
index 000000000..bef28253f
--- /dev/null
+++ b/api/pkg/emails/event_payload_formatter.go
@@ -0,0 +1,126 @@
+package emails
+
+import (
+	"bytes"
+	"encoding/json"
+	"html"
+	"html/template"
+	"strings"
+)
+
+const (
+	eventPayloadCodeBlockStyle = "margin:0;padding:12px;border:1px solid #D0D7DE;border-radius:6px;background:#F6F8FA;color:#24292F;font-family:Consolas,Monaco,'Courier New',monospace;font-size:13px;line-height:1.5;white-space:pre-wrap;word-break:break-word;overflow-wrap:anywhere;"
+	jsonKeyStyle               = "color:#0550AE;font-weight:600;"
+	jsonStringStyle            = "color:#0A3069;"
+	jsonNumberStyle            = "color:#953800;"
+	jsonLiteralStyle           = "color:#8250DF;"
+)
+
+func formatEventPayload(payload string) (string, template.HTML) {
+	formattedPayload, isJSON := indentEventPayloadJSON(payload)
+	content := html.EscapeString(formattedPayload)
+	if isJSON {
+		content = highlightEventPayloadJSON(formattedPayload)
+	}
+
+	richPayload := template.HTML(`<pre style="` + eventPayloadCodeBlockStyle + `">` + content + `</pre>`)
+	return formattedPayload, richPayload
+}
+
+func indentEventPayloadJSON(payload string) (string, bool) {
+	var formatted bytes.Buffer
+	if err := json.Indent(&formatted, []byte(payload), "", "  "); err != nil {
+		return payload, false
+	}
+
+	return formatted.String(), true
+}
+
+func highlightEventPayloadJSON(payload string) string {
+	var highlighted strings.Builder
+	highlighted.Grow(len(payload))
+
+	for index := 0; index < len(payload); {
+		switch {
+		case payload[index] == '"':
+			end := eventPayloadJSONStringEnd(payload, index)
+			style := jsonStringStyle
+			if eventPayloadNextNonSpace(payload, end) == ':' {
+				style = jsonKeyStyle
+			}
+			writeEventPayloadToken(&highlighted, style, payload[index:end])
+			index = end
+		case payload[index] == '-' || isEventPayloadDigit(payload[index]):
+			end := index + 1
+			for end < len(payload) && isEventPayloadNumberCharacter(payload[end]) {
+				end++
+			}
+			writeEventPayloadToken(&highlighted, jsonNumberStyle, payload[index:end])
+			index = end
+		case strings.HasPrefix(payload[index:], "true"):
+			writeEventPayloadToken(&highlighted, jsonLiteralStyle, "true")
+			index += len("true")
+		case strings.HasPrefix(payload[index:], "false"):
+			writeEventPayloadToken(&highlighted, jsonLiteralStyle, "false")
+			index += len("false")
+		case strings.HasPrefix(payload[index:], "null"):
+			writeEventPayloadToken(&highlighted, jsonLiteralStyle, "null")
+			index += len("null")
+		default:
+			highlighted.WriteString(html.EscapeString(payload[index : index+1]))
+			index++
+		}
+	}
+
+	return highlighted.String()
+}
+
+func eventPayloadJSONStringEnd(payload string, start int) int {
+	escaped := false
+	for index := start + 1; index < len(payload); index++ {
+		switch {
+		case escaped:
+			escaped = false
+		case payload[index] == '\\':
+			escaped = true
+		case payload[index] == '"':
+			return index + 1
+		}
+	}
+
+	return len(payload)
+}
+
+func eventPayloadNextNonSpace(payload string, start int) byte {
+	for index := start; index < len(payload); index++ {
+		switch payload[index] {
+		case ' ', '\n', '\r', '\t':
+			continue
+		default:
+			return payload[index]
+		}
+	}
+
+	return 0
+}
+
+func isEventPayloadDigit(value byte) bool {
+	return value >= '0' && value <= '9'
+}
+
+func isEventPayloadNumberCharacter(value byte) bool {
+	return isEventPayloadDigit(value) ||
+		value == '-' ||
+		value == '+' ||
+		value == '.' ||
+		value == 'e' ||
+		value == 'E'
+}
+
+func writeEventPayloadToken(builder *strings.Builder, style string, token string) {
+	builder.WriteString(`<span style="`)
+	builder.WriteString(style)
+	builder.WriteString(`">`)
+	builder.WriteString(html.EscapeString(token))
+	builder.WriteString(`</span>`)
+}
diff --git a/api/pkg/emails/event_payload_formatter_test.go b/api/pkg/emails/event_payload_formatter_test.go
new file mode 100644
index 000000000..3f963c2c7
--- /dev/null
+++ b/api/pkg/emails/event_payload_formatter_test.go
@@ -0,0 +1,58 @@
+package emails
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestFormatEventPayloadIndentsAndHighlightsJSON(t *testing.T) {
+	payload := `{"message":"hello","count":2,"ratio":1.5,"enabled":true,"disabled":false,"missing":null,"nested":{"value":"ok"}}`
+
+	plain, rich := formatEventPayload(payload)
+	html := string(rich)
+
+	assert.Equal(t, `{
+  "message": "hello",
+  "count": 2,
+  "ratio": 1.5,
+  "enabled": true,
+  "disabled": false,
+  "missing": null,
+  "nested": {
+    "value": "ok"
+  }
+}`, plain)
+	assert.Contains(t, html, `<span style="color:#0550AE;font-weight:600;">&#34;message&#34;</span>`)
+	assert.Contains(t, html, `<span style="color:#0A3069;">&#34;hello&#34;</span>`)
+	assert.Contains(t, html, `<span style="color:#953800;">2</span>`)
+	assert.Contains(t, html, `<span style="color:#953800;">1.5</span>`)
+	assert.Contains(t, html, `<span style="color:#8250DF;">true</span>`)
+	assert.Contains(t, html, `<span style="color:#8250DF;">false</span>`)
+	assert.Contains(t, html, `<span style="color:#8250DF;">null</span>`)
+	assert.Contains(t, html, `white-space:pre-wrap`)
+}
+
+func TestFormatEventPayloadEscapesPayloadHTML(t *testing.T) {
+	plain, rich := formatEventPayload(`{"message":"<script>alert(\"x\")</script>&"}`)
+	html := string(rich)
+
+	assert.Contains(t, plain, `<script>alert`)
+	assert.NotContains(t, html, `<script>`)
+	assert.Contains(t, html, `&lt;script&gt;`)
+	assert.Contains(t, html, `&amp;`)
+}
+
+func TestFormatEventPayloadPreservesInvalidJSONWithoutHighlighting(t *testing.T) {
+	payload := "line one\n  <strong>line two</strong>"
+
+	plain, rich := formatEventPayload(payload)
+	html := string(rich)
+
+	assert.Equal(t, payload, plain)
+	assert.Contains(t, html, "line one\n  &lt;strong&gt;line two&lt;/strong&gt;")
+	assert.NotContains(t, html, `<strong>`)
+	assert.NotContains(t, html, `<span style="color:`)
+	assert.Equal(t, 1, strings.Count(html, `<pre style=`))
+}

From 6d1e18a8091b7f6eb14173579243c33f613b6e62 Mon Sep 17 00:00:00 2001
From: Acho Arnold Ewin <arnold@ndolestudio.com>
Date: Sat, 18 Jul 2026 10:42:51 +0300
Subject: [PATCH 5/8] feat(api): render rich email dictionary values

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 48f6d946-ae22-4440-b7a1-44e939419b11
---
 api/pkg/emails/hermes_theme.go      |  2 +-
 api/pkg/emails/hermes_theme_test.go | 46 +++++++++++++++++++++++++++++
 2 files changed, 47 insertions(+), 1 deletion(-)
 create mode 100644 api/pkg/emails/hermes_theme_test.go

diff --git a/api/pkg/emails/hermes_theme.go b/api/pkg/emails/hermes_theme.go
index 9d8cc4716..34e35d5cc 100644
--- a/api/pkg/emails/hermes_theme.go
+++ b/api/pkg/emails/hermes_theme.go
@@ -327,7 +327,7 @@ func (dt *hermesTheme) HTMLTemplate() string {
                           <dl class="body-dictionary">
                             {{ range $entry := . }}
                               <dt>{{ $entry.Key }}:</dt>
-                              <dd>{{ $entry.Value }}</dd>
+                              <dd>{{ if $entry.UnsafeValue }}{{ $entry.UnsafeValue }}{{ else }}{{ $entry.Value }}{{ end }}</dd>
                             {{ end }}
                           </dl>
                         {{ end }}
diff --git a/api/pkg/emails/hermes_theme_test.go b/api/pkg/emails/hermes_theme_test.go
new file mode 100644
index 000000000..25b695087
--- /dev/null
+++ b/api/pkg/emails/hermes_theme_test.go
@@ -0,0 +1,46 @@
+package emails
+
+import (
+	"html/template"
+	"testing"
+
+	"github.com/go-hermes/hermes/v2"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestHermesThemeRendersUnsafeDictionaryValueOnlyWhenProvided(t *testing.T) {
+	generator := (&HermesGeneratorConfig{
+		AppURL:     "https://httpsms.com",
+		AppName:    "httpSMS",
+		AppLogoURL: "https://httpsms.com/logo.png",
+	}).Generator()
+
+	email := hermes.Email{
+		Body: hermes.Body{
+			Title: "Hello",
+			Dictionary: []hermes.Entry{
+				{Key: "Normal", Value: "<b>escaped</b>"},
+				{
+					Key:         "Payload",
+					Value:       "plain payload",
+					UnsafeValue: template.HTML(`<pre style="white-space:pre-wrap">rich payload</pre>`),
+				},
+			},
+		},
+	}
+
+	htmlEmail, err := generator.GenerateHTML(email)
+	require.NoError(t, err)
+
+	textEmail, err := generator.GeneratePlainText(email)
+	require.NoError(t, err)
+
+	assert.Contains(t, htmlEmail, `&lt;b&gt;escaped&lt;/b&gt;`)
+	assert.NotContains(t, htmlEmail, `<b>escaped</b>`)
+	assert.Contains(t, htmlEmail, `<pre style="white-space:pre-wrap">rich payload</pre>`)
+	assert.NotContains(t, htmlEmail, `<dd>plain payload</dd>`)
+	assert.Contains(t, textEmail, "Normal: <b>escaped</b>")
+	assert.Contains(t, textEmail, "Payload: plain payload")
+	assert.NotContains(t, textEmail, "<pre")
+}

From f58a74ea25c1b14dfb169da25349072e5b00d0b4 Mon Sep 17 00:00:00 2001
From: Acho Arnold Ewin <arnold@ndolestudio.com>
Date: Sat, 18 Jul 2026 10:48:34 +0300
Subject: [PATCH 6/8] feat(api): highlight webhook email payload

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 48f6d946-ae22-4440-b7a1-44e939419b11
---
 .../hermes_notification_email_factory.go      | 30 +++++++-
 .../hermes_notification_email_factory_test.go | 76 +++++++++++++++++++
 2 files changed, 105 insertions(+), 1 deletion(-)
 create mode 100644 api/pkg/emails/hermes_notification_email_factory_test.go

diff --git a/api/pkg/emails/hermes_notification_email_factory.go b/api/pkg/emails/hermes_notification_email_factory.go
index 7c4b7bc59..24f58b70d 100644
--- a/api/pkg/emails/hermes_notification_email_factory.go
+++ b/api/pkg/emails/hermes_notification_email_factory.go
@@ -2,6 +2,7 @@ package emails
 
 import (
 	"fmt"
+	"strings"
 	"time"
 
 	"github.com/NdoleStudio/httpsms/pkg/events"
@@ -76,6 +77,8 @@ func (factory *hermesNotificationEmailFactory) DiscordSendFailed(user *entities.
 }
 
 func (factory *hermesNotificationEmailFactory) WebhookSendFailed(user *entities.User, payload *events.WebhookSendFailedPayload) (*Email, error) {
+	formattedPayload, formattedPayloadHTML := formatEventPayload(payload.EventPayload)
+
 	email := hermes.Email{
 		Body: hermes.Body{
 			Title: "Hello",
@@ -89,7 +92,11 @@ func (factory *hermesNotificationEmailFactory) WebhookSendFailed(user *entities.
 				{Key: "Phone Number", Value: factory.formatPhoneNumber(payload.Owner)},
 				{Key: "HTTP Response Code", Value: factory.formatHTTPResponseCode(payload.HTTPResponseStatusCode)},
 				{Key: "Error Message / HTTP Response", Value: payload.ErrorMessage},
-				{Key: "Event Payload", Value: payload.EventPayload},
+				{
+					Key:         "Event Payload",
+					Value:       formattedPayload,
+					UnsafeValue: formattedPayloadHTML,
+				},
 			},
 			Actions: []hermes.Action{
 				{
@@ -118,6 +125,7 @@ func (factory *hermesNotificationEmailFactory) WebhookSendFailed(user *entities.
 	if err != nil {
 		return nil, stacktrace.Propagate(err, "cannot generate text email")
 	}
+	text = formatWebhookSendFailedTextPayload(text, formattedPayload)
 
 	return &Email{
 		ToEmail: user.Email,
@@ -127,6 +135,26 @@ func (factory *hermesNotificationEmailFactory) WebhookSendFailed(user *entities.
 	}, nil
 }
 
+func formatWebhookSendFailedTextPayload(text string, formattedPayload string) string {
+	const (
+		eventPayloadPrefix = "* Event Payload: "
+		nextSectionPrefix  = "\n\nUsually this error happens"
+	)
+
+	start := strings.Index(text, eventPayloadPrefix)
+	if start == -1 {
+		return text
+	}
+
+	end := strings.Index(text[start:], nextSectionPrefix)
+	if end == -1 {
+		return text
+	}
+
+	end += start
+	return text[:start] + eventPayloadPrefix + formattedPayload + text[end:]
+}
+
 func (factory *hermesNotificationEmailFactory) MessageExpired(user *entities.User, payload *events.MessageSendExpiredPayload) (*Email, error) {
 	email := hermes.Email{
 		Body: hermes.Body{
diff --git a/api/pkg/emails/hermes_notification_email_factory_test.go b/api/pkg/emails/hermes_notification_email_factory_test.go
new file mode 100644
index 000000000..656f5de59
--- /dev/null
+++ b/api/pkg/emails/hermes_notification_email_factory_test.go
@@ -0,0 +1,76 @@
+package emails
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/NdoleStudio/httpsms/pkg/entities"
+	"github.com/NdoleStudio/httpsms/pkg/events"
+	"github.com/google/uuid"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func testNotificationEmailFactory() NotificationEmailFactory {
+	return NewHermesNotificationEmailFactory(&HermesGeneratorConfig{
+		AppURL:     "https://httpsms.com",
+		AppName:    "httpSMS",
+		AppLogoURL: "https://httpsms.com/logo.png",
+	})
+}
+
+func TestWebhookSendFailedFormatsOnlyEventPayload(t *testing.T) {
+	statusCode := 500
+	factory := testNotificationEmailFactory()
+	user := &entities.User{
+		Email:    "name@email.com",
+		Timezone: "UTC",
+	}
+	payload := &events.WebhookSendFailedPayload{
+		WebhookID:              uuid.New(),
+		WebhookURL:             "https://example.com/webhooks",
+		Owner:                  "+237612345678",
+		EventID:                "event-id",
+		EventType:              "message.phone.received",
+		EventPayload:           `{"message":"hello","retry":false}`,
+		HTTPResponseStatusCode: &statusCode,
+		ErrorMessage:           "plain failure response",
+	}
+
+	email, err := factory.WebhookSendFailed(user, payload)
+	require.NoError(t, err)
+
+	assert.Equal(t, "name@email.com", email.ToEmail)
+	assert.Equal(t, "📢 We could not forward a webhook event to your server", email.Subject)
+	assert.Contains(t, email.HTML, `<pre style=`)
+	assert.Equal(t, 1, strings.Count(email.HTML, `<pre style=`))
+	assert.Contains(t, email.HTML, `&#34;message&#34;`)
+	assert.Contains(t, email.HTML, `plain failure response`)
+	assert.Contains(t, email.Text, `"message": "hello"`)
+	assert.Contains(t, email.Text, `"retry": false`)
+	assert.NotContains(t, email.Text, "<pre")
+}
+
+func TestWebhookSendFailedPreservesNonJSONEventPayload(t *testing.T) {
+	factory := testNotificationEmailFactory()
+	user := &entities.User{
+		Email:    "name@email.com",
+		Timezone: "UTC",
+	}
+	payload := &events.WebhookSendFailedPayload{
+		WebhookID:    uuid.New(),
+		WebhookURL:   "https://example.com/webhooks",
+		Owner:        "+237612345678",
+		EventID:      "event-id",
+		EventType:    "message.phone.received",
+		EventPayload: "line one\n  line two",
+		ErrorMessage: "plain failure response",
+	}
+
+	email, err := factory.WebhookSendFailed(user, payload)
+	require.NoError(t, err)
+
+	assert.Contains(t, email.HTML, "line one\n  line two")
+	assert.NotContains(t, email.HTML, `<span style="color:`)
+	assert.Contains(t, email.Text, "line one\n  line two")
+}

From 19b221a525f2dbda403885cbe4832340d9fc16cd Mon Sep 17 00:00:00 2001
From: Acho Arnold Ewin <arnold@ndolestudio.com>
Date: Sat, 18 Jul 2026 11:01:59 +0300
Subject: [PATCH 7/8] fix(api): restore webhook payload text

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .../hermes_notification_email_factory.go      | 27 ++++---------------
 1 file changed, 5 insertions(+), 22 deletions(-)

diff --git a/api/pkg/emails/hermes_notification_email_factory.go b/api/pkg/emails/hermes_notification_email_factory.go
index 24f58b70d..b305471bb 100644
--- a/api/pkg/emails/hermes_notification_email_factory.go
+++ b/api/pkg/emails/hermes_notification_email_factory.go
@@ -18,6 +18,8 @@ type hermesNotificationEmailFactory struct {
 	generator hermes.Hermes
 }
 
+const webhookSendFailedEventPayloadPlaceholder = "__HTTPSMS_WEBHOOK_SEND_FAILED_EVENT_PAYLOAD__"
+
 // NewHermesNotificationEmailFactory creates a new instance of the UserEmailFactory
 func NewHermesNotificationEmailFactory(config *HermesGeneratorConfig) NotificationEmailFactory {
 	return &hermesNotificationEmailFactory{
@@ -94,7 +96,7 @@ func (factory *hermesNotificationEmailFactory) WebhookSendFailed(user *entities.
 				{Key: "Error Message / HTTP Response", Value: payload.ErrorMessage},
 				{
 					Key:         "Event Payload",
-					Value:       formattedPayload,
+					Value:       webhookSendFailedEventPayloadPlaceholder,
 					UnsafeValue: formattedPayloadHTML,
 				},
 			},
@@ -125,7 +127,8 @@ func (factory *hermesNotificationEmailFactory) WebhookSendFailed(user *entities.
 	if err != nil {
 		return nil, stacktrace.Propagate(err, "cannot generate text email")
 	}
-	text = formatWebhookSendFailedTextPayload(text, formattedPayload)
+	// Hermes/html2text collapses dictionary whitespace, so restore the payload after plain-text generation.
+	text = strings.Replace(text, webhookSendFailedEventPayloadPlaceholder, formattedPayload, 1)
 
 	return &Email{
 		ToEmail: user.Email,
@@ -135,26 +138,6 @@ func (factory *hermesNotificationEmailFactory) WebhookSendFailed(user *entities.
 	}, nil
 }
 
-func formatWebhookSendFailedTextPayload(text string, formattedPayload string) string {
-	const (
-		eventPayloadPrefix = "* Event Payload: "
-		nextSectionPrefix  = "\n\nUsually this error happens"
-	)
-
-	start := strings.Index(text, eventPayloadPrefix)
-	if start == -1 {
-		return text
-	}
-
-	end := strings.Index(text[start:], nextSectionPrefix)
-	if end == -1 {
-		return text
-	}
-
-	end += start
-	return text[:start] + eventPayloadPrefix + formattedPayload + text[end:]
-}
-
 func (factory *hermesNotificationEmailFactory) MessageExpired(user *entities.User, payload *events.MessageSendExpiredPayload) (*Email, error) {
 	email := hermes.Email{
 		Body: hermes.Body{

From df260ed06a503d74f55e41e1569cfc1d504bf29d Mon Sep 17 00:00:00 2001
From: Acho Arnold Ewin <arnold@ndolestudio.com>
Date: Sat, 18 Jul 2026 11:10:43 +0300
Subject: [PATCH 8/8] fix(api): harden webhook payload formatting

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 api/pkg/emails/event_payload_formatter.go     |  2 +
 .../emails/event_payload_formatter_test.go    | 55 +++++++++++++++++++
 .../hermes_notification_email_factory.go      | 11 +++-
 .../hermes_notification_email_factory_test.go | 29 ++++++++++
 4 files changed, 96 insertions(+), 1 deletion(-)

diff --git a/api/pkg/emails/event_payload_formatter.go b/api/pkg/emails/event_payload_formatter.go
index bef28253f..130aaf6f1 100644
--- a/api/pkg/emails/event_payload_formatter.go
+++ b/api/pkg/emails/event_payload_formatter.go
@@ -23,6 +23,7 @@ func formatEventPayload(payload string) (string, template.HTML) {
 		content = highlightEventPayloadJSON(formattedPayload)
 	}
 
+	// Every payload token is escaped before this trusted wrapper is constructed.
 	richPayload := template.HTML(`<pre style="` + eventPayloadCodeBlockStyle + `">` + content + `</pre>`)
 	return formattedPayload, richPayload
 }
@@ -52,6 +53,7 @@ func highlightEventPayloadJSON(payload string) string {
 			index = end
 		case payload[index] == '-' || isEventPayloadDigit(payload[index]):
 			end := index + 1
+			// json.Indent already validated this as JSON, so this continuation set only sees JSON number bytes.
 			for end < len(payload) && isEventPayloadNumberCharacter(payload[end]) {
 				end++
 			}
diff --git a/api/pkg/emails/event_payload_formatter_test.go b/api/pkg/emails/event_payload_formatter_test.go
index 3f963c2c7..9617ebb0e 100644
--- a/api/pkg/emails/event_payload_formatter_test.go
+++ b/api/pkg/emails/event_payload_formatter_test.go
@@ -56,3 +56,58 @@ func TestFormatEventPayloadPreservesInvalidJSONWithoutHighlighting(t *testing.T)
 	assert.NotContains(t, html, `<span style="color:`)
 	assert.Equal(t, 1, strings.Count(html, `<pre style=`))
 }
+
+func TestFormatEventPayloadHandlesTopLevelPayloadShapes(t *testing.T) {
+	tests := []struct {
+		name                string
+		payload             string
+		wantPlain           string
+		wantHTMLContains    []string
+		wantHTMLNotContains []string
+	}{
+		{
+			name:                "empty payload falls back to unhighlighted block",
+			payload:             "",
+			wantPlain:           "",
+			wantHTMLContains:    []string{`<pre style="`, `</pre>`},
+			wantHTMLNotContains: []string{`<span style="color:`},
+		},
+		{
+			name:                "top-level number stays valid JSON",
+			payload:             "42",
+			wantPlain:           "42",
+			wantHTMLContains:    []string{`<span style="color:#953800;">42</span>`},
+			wantHTMLNotContains: []string{`color:#0550AE`},
+		},
+		{
+			name:      "json array stays readable and escaped",
+			payload:   `[{"message":"<b>safe</b>"},true,null,3]`,
+			wantPlain: "[\n  {\n    \"message\": \"<b>safe</b>\"\n  },\n  true,\n  null,\n  3\n]",
+			wantHTMLContains: []string{
+				"[\n  {",
+				`&#34;message&#34;`,
+				`&lt;b&gt;safe&lt;/b&gt;`,
+				`<span style="color:#953800;">3</span>`,
+			},
+			wantHTMLNotContains: []string{`<b>safe</b>`},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			plain, rich := formatEventPayload(tt.payload)
+			html := string(rich)
+
+			assert.Equal(t, tt.wantPlain, plain)
+			assert.Equal(t, 1, strings.Count(html, `<pre style=`))
+
+			for _, want := range tt.wantHTMLContains {
+				assert.Contains(t, html, want)
+			}
+
+			for _, unwanted := range tt.wantHTMLNotContains {
+				assert.NotContains(t, html, unwanted)
+			}
+		})
+	}
+}
diff --git a/api/pkg/emails/hermes_notification_email_factory.go b/api/pkg/emails/hermes_notification_email_factory.go
index b305471bb..73f129def 100644
--- a/api/pkg/emails/hermes_notification_email_factory.go
+++ b/api/pkg/emails/hermes_notification_email_factory.go
@@ -128,7 +128,7 @@ func (factory *hermesNotificationEmailFactory) WebhookSendFailed(user *entities.
 		return nil, stacktrace.Propagate(err, "cannot generate text email")
 	}
 	// Hermes/html2text collapses dictionary whitespace, so restore the payload after plain-text generation.
-	text = strings.Replace(text, webhookSendFailedEventPayloadPlaceholder, formattedPayload, 1)
+	text = replaceWebhookSendFailedEventPayloadPlaceholder(text, formattedPayload)
 
 	return &Email{
 		ToEmail: user.Email,
@@ -138,6 +138,15 @@ func (factory *hermesNotificationEmailFactory) WebhookSendFailed(user *entities.
 	}, nil
 }
 
+func replaceWebhookSendFailedEventPayloadPlaceholder(text string, formattedPayload string) string {
+	before, after, found := strings.Cut(text, webhookSendFailedEventPayloadPlaceholder)
+	if !found {
+		return text
+	}
+
+	return before + formattedPayload + after
+}
+
 func (factory *hermesNotificationEmailFactory) MessageExpired(user *entities.User, payload *events.MessageSendExpiredPayload) (*Email, error) {
 	email := hermes.Email{
 		Body: hermes.Body{
diff --git a/api/pkg/emails/hermes_notification_email_factory_test.go b/api/pkg/emails/hermes_notification_email_factory_test.go
index 656f5de59..37c9333a6 100644
--- a/api/pkg/emails/hermes_notification_email_factory_test.go
+++ b/api/pkg/emails/hermes_notification_email_factory_test.go
@@ -49,6 +49,7 @@ func TestWebhookSendFailedFormatsOnlyEventPayload(t *testing.T) {
 	assert.Contains(t, email.Text, `"message": "hello"`)
 	assert.Contains(t, email.Text, `"retry": false`)
 	assert.NotContains(t, email.Text, "<pre")
+	assert.NotContains(t, email.Text, webhookSendFailedEventPayloadPlaceholder)
 }
 
 func TestWebhookSendFailedPreservesNonJSONEventPayload(t *testing.T) {
@@ -74,3 +75,31 @@ func TestWebhookSendFailedPreservesNonJSONEventPayload(t *testing.T) {
 	assert.NotContains(t, email.HTML, `<span style="color:`)
 	assert.Contains(t, email.Text, "line one\n  line two")
 }
+
+func TestReplaceWebhookSendFailedEventPayloadPlaceholder(t *testing.T) {
+	tests := []struct {
+		name             string
+		text             string
+		formattedPayload string
+		want             string
+	}{
+		{
+			name:             "replaces placeholder and preserves remaining text",
+			text:             "before\n" + webhookSendFailedEventPayloadPlaceholder + "\nafter",
+			formattedPayload: "{\n  \"message\": \"hello\"\n}",
+			want:             "before\n{\n  \"message\": \"hello\"\n}\nafter",
+		},
+		{
+			name:             "returns original text when placeholder is missing",
+			text:             "before\nafter",
+			formattedPayload: "{\n  \"message\": \"hello\"\n}",
+			want:             "before\nafter",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			assert.Equal(t, tt.want, replaceWebhookSendFailedEventPayloadPlaceholder(tt.text, tt.formattedPayload))
+		})
+	}
+}