JAlcocerTech E-books

One Forms Backend for Every Site

Before the engine, my sites collected leads five ways: a KV function on one site, a form relay service on another, a hosted survey for the consulting qualifier, a booking tool, and a database on the homelab behind the audit tool. Two contact addresses, different consent wording everywhere, and no single answer to “who wrote to me this month?”.

Now every form on every site posts to the same Worker, on the site’s own domain.

The shape of a form

Every form is plain HTML that works without JavaScript:

<form action="/api/forms/submit" method="POST">
  <input type="hidden" name="kind" value="enquiry">
  <input name="name" required>
  <input name="email" type="email" required>
  <textarea name="details"></textarea>

  <!-- Honeypot: hidden from people, tempting to bots -->
  <input name="company_website" tabindex="-1" autocomplete="off" class="hidden">

  <label>
    <input type="checkbox" name="consent_marketing">
    Also send me occasional updates (optional)
  </label>
  <button>Send</button>
</form>

Without JavaScript, the browser posts the form and the Worker answers with a 303 redirect back to the same page with ?form=sent, and the page shows a thank-you message. With JavaScript, a small script intercepts the submit, posts JSON with fetch, and shows the result in place: “Sent”, or “Check your inbox to confirm” when double opt-in applies.

Rules every form follows:

  • Same-origin. action="/api/forms/submit" on the site’s own domain. No third-party script or URL on the page.
  • A honeypot, not a CAPTCHA. A field people can’t see. If it’s filled in, the Worker answers “accepted” and stores nothing.
  • Optional consent is its own unticked box, never bundled into a required checkbox (chapter 3).
  • One error fallback: “That didn’t go through. Please email …”, so a failure never dead-ends.

What the Worker does with a submission

sequenceDiagram
  participant B as Browser
  participant W as Forms Worker
  participant KV as KV
  participant N as ntfy (phone)
  B->>W: POST /api/forms/submit
  W->>W: which site? (from Host) · Origin check · honeypot · validation · consent
  W->>KV: put site:kind:time:uuid (TTL per kind, metadata)
  W-->>B: 202 (JSON) or 303 back to the page (no JS)
  W--)N: alert: kind, site, email domain only

Three design choices carry most of the weight.

1. A site registry in code. One file lists every site: its hostnames, its profile, the form kinds it accepts, the version of its consent wording, its sender name. Unknown sites and unknown kinds are rejected. Adding a site means one entry in that file, one route, and a form.

{
  id: "consulting.example.com",
  profile: "growth",                  // may store optional marketing consent
  kinds: ["enquiry", "qualifier", "booking"],
  hosts: ["consulting.example.com"],
  consentTextVersion: "2026-10-01",
  brand: "Example Consulting",
}

There are two profiles. A respond site uses the data only to answer what was asked (a technical blog). A growth site may also record optional marketing consent. A marketing tick from a respond site is ignored, not stored.

2. Store first, everything else after. The lead is written to KV before the visitor gets an answer. Alerts and emails run afterwards in ctx.waitUntil, so a slow notification server or email provider never loses a lead or delays the visitor.

3. Retention as data. Every kind has a lifetime, applied as the KV TTL when the lead is written:

KindKept forWhy
enquiry, ebook24 monthsWhat the privacy pages promise
qualifier90 daysAnswers from people who don’t book aren’t needed
booking, audit24 monthsBusiness record
newsletterUntil unsubscribePending or unsubscribed: 30 days, then gone

What a stored lead looks like

{
  "site": "consulting.example.com",
  "profile": "growth",
  "kind": "enquiry",
  "email": "[email protected]",
  "name": "Ana",
  "details": "We need a self-hosted analytics stack…",
  "consent": { "marketing": true, "text_version": "2026-10-01", "at": "2026-10-04T09:12:44Z" },
  "attribution": { "page": "/pricing", "referrer": "https://www.linkedin.com/", "utm_source": "linkedin" },
  "receivedAt": "2026-10-04T09:12:44Z",
  "country": "PL"
}

Consent is a data structure: what was agreed, when, and which version of the wording was on screen. Attribution (page, referrer, UTM tags) comes with every lead, so “where do my leads come from?” is answerable later.

Phone alerts that don’t leak

The alert goes to a self-hosted ntfy server (chapter 4) and carries the kind, the site and the email domain only: “enquiry from @example.org on consulting”. The address and the message stay in KV. A notification sits on a lock screen and passes through a push service; it shouldn’t carry personal data.

Leads that don’t come from browsers

Two sources aren’t forms:

  • The audit tool’s backend forwards audit leads server-to-server. Because anyone could post that kind from a browser, kinds marked as server-only need a shared secret in an X-Forms-Key header, compared in constant time. The forward is best-effort: if the Worker is unreachable, the audit still completes for the visitor.
  • Paid bookings arrive from Cal.com as a webhook. The Worker verifies the HMAC signature (X-Cal-Signature-256) over the raw body, stores only scheduling facts (who, when, which event, paid or not; no free-text notes) and sends an urgent “PAID BOOKING” alert.

Spam without friction

Scripted “sales pitches” sailed past the honeypot because a person (or a better script) fills them in. A sender blocklist in the Worker catches them by email domain. Matches are stored under spam: for 30 days, never alerted and never emailed, so a false positive can be found and rescued. Turnstile or a CAPTCHA stays deferred until the blocklist stops being enough: every visitor would pay that friction to stop a handful of messages.

Testing every state without sending an email

The states a form can show (sent, check your inbox, error, the no-JS return) are tested with Playwright route mocking against the built site: the test intercepts /api/forms/submit and answers with each response in turn. No email is sent, no lead is stored, and every message is checked.

Next: consent and email.