How-To / Examples

Task-oriented recipes. Each page answers a specific question: how do I do X? Most assume you already have a working deployment — start with Getting Started if you don’t.

Recipes

Deployment

  • Getting Started — set webform-relay up as a vendored subproject of your own repo with v: vendor the source, include its taskfile from your own Taskfile.yml, split config between a gitignored .env and a committed .env.project, create a least-privilege deploy IAM user, deploy, update, deploy from CI/CD, roll back, add the optional S3 submissions storage relay, and tear down; ends with the flow’s known gaps (secret handling, single-environment config, global-only throttling, partial teardown)
  • Vendoring Alternatives — bringing the source in without v: a plain copy of a release, or a git submodule, and what each costs. Everything after the include block is identical to Getting Started

Integration examples

  • Fan-out: email, S3, and Salesforce Web2Lead — name/email/feedback form that emails a notification, stores raw submissions to S3, and creates a Salesforce lead with custom field mapping. Includes a full S3 storage walkthrough — deploying the bucket and its write-only endpoint, wiring the output, reading submissions back, costs, retention, and teardown
  • Send form submissions via SMTP — deliver submissions as plain-text email over SMTP with STARTTLS or implicit TLS; includes config for Gmail, SendGrid, and Mailgun
  • Route submissions to Salesforce Web2Lead — create Salesforce leads from form submissions with field mapping and static values; includes fan-out with email notification
  • Reveal content when the correct value is entered — a show_when gate: a text field that hides itself and reveals an HTML block once the correct value is typed, re-rendered server-side over htmx (a soft gate, not authentication)

Development

Setting up a development environment, running the API locally, and the test and lint loop are in the Contribution Guide.

  • How to add a new field to the submission payload
  • How to write and run a unit test for the handler

Operations

  • How to tail CloudWatch logs (task relay:logs:tail)
  • How to roll back to the previous deployment (task relay:deploy:rollback)
  • How to set environment variables via SAM parameters
  • How to store raw submissions in S3 (task relay:deploy:submissions)

Integration

  • How to POST from a plain HTML form
  • How to POST from JavaScript (fetch)
  • How to verify a submission reached its destination

Infrastructure

  • How to restrict the endpoint to specific origins (CORS) — shipped; see the AllowedOrigins parameter in template.yaml and ALLOWED_ORIGINS in .env.project
  • How to add rate limiting at the API Gateway level
  • How to use a custom domain name