Form-to-webhook with file uploads (embeddable forms for AI agents)

Forms are everywhere — contact forms, lead-capture forms, support intake, application forms, surveys. They're a high-intent moment: the user is choosing to give you structured information. For AI agents, forms are one of the highest-signal triggers possible.

The catch: receiving a form submission reliably (especially with file uploads) is more work than it sounds. CORS for cross-origin embeds, multipart parsing, file storage, validation, abuse prevention — every step is its own miniature project.

This guide covers what form-to-webhook actually does, how Hooksbase's form ingest handles each step, and the agent use cases that depend on it.

What form-to-webhook does

Form-to-webhook accepts an HTTP POST from an HTML form (multipart/form-data or application/x-www-form-urlencoded), parses the submission into structured JSON, stores paid-tier files separately, and delivers the result to your agent's HTTP endpoint.

The flow:

1. You create a webhook in Hooksbase with a form ingest URL (POST /v1/form/:publicId).
2. You point an HTML form's action attribute at that URL.
3. When the form is submitted, Hooksbase parses the fields, stores uploaded files in R2 on paid tiers, and delivers a JSON payload to your destination.
4. Your agent processes the structured submission like any other webhook event.

The agent's endpoint receives the form fields as a structured object plus signed file references for paid-tier uploads. On Free, file entries include metadata only.

What you skip by not building this yourself

Receiving a form submission with files in your own backend means:

• An HTTP endpoint accepting multipart/form-data and parsing it correctly
• File storage — somewhere durable, with size limits, with virus scanning if you're paranoid
• CORS configuration so the form can be embedded on third-party domains
• CSRF protection if the form is on a domain you control with cookie-based auth
• Validation — fields, types, sizes, required-or-not
• Spam prevention — CAPTCHA or similar; rate limiting per IP
• A delivery layer to get the parsed submission to wherever processes it

Each of these is solvable. None of them are the work the agent actually does.

How Hooksbase form ingest works

Hooksbase exposes POST /v1/form/:publicId per webhook. The endpoint:

• Accepts multipart/form-data and application/x-www-form-urlencoded
• Stores file uploads in R2 with signed URLs on paid tiers; Free gets metadata-only file entries
• Sets CORS headers permissively so the form can be embedded on any origin
• Applies the same routing, transforms, retries, and replay primitives as HTTP webhook ingest

A typical embedded form:

<form
  action="https://hooks.hooksbase.com/v1/form/wh_xyz123abc"
  method="POST"
  enctype="multipart/form-data"
>
  <input name="email" type="email" required />
  <input name="message" type="text" required />
  <input name="screenshot" type="file" accept="image/*" />
  <button type="submit">Send</button>
</form>

When this submits, Hooksbase parses the multipart body, uploads screenshot to R2, and delivers the result to your destination as JSON:

{
"source": "form",
"fields": {
  "email": "customer@example.com",
  "message": "Issue with my account"
},
"files": [
  {
    "fieldName": "screenshot",
    "filename": "screenshot.png",
    "contentType": "image/png",
    "size": 142357,
    "fileRef": {
      "key": "files/...",
      "url": "https://hooks.hooksbase.com/v1/files/<signed>"
    }
  }
]
}

Common form-to-webhook use cases for AI agents

The patterns that show up across teams:

• Lead qualification agent — demo-request forms trigger an agent that enriches the company, scores the lead, and routes to the right SDR.
• Support intake agent — contact forms (with optional screenshots) trigger an agent that classifies the request, attaches related docs, and either auto-resolves or escalates.
• Application screening agent — job applications (with resume PDFs) trigger an agent that pre-screens against role criteria and surfaces strong candidates.
• Onboarding intake agent — new-customer onboarding forms trigger an agent that provisions resources based on the answers and emails the welcome sequence.
• Insurance / claim agents — claims forms (with photos and documents) trigger an agent that extracts the structured data, validates against policy, and routes to the right adjuster.
• Survey-and-research agents — feedback or research forms trigger an agent that classifies the response, extracts themes, and updates a research dashboard.

In every case, the form is the trigger and the agent is the action. The relay layer makes it reliable.

Validation and abuse prevention

Open form ingest URLs need protection. Hooksbase's defaults plus a few add-on patterns cover the common cases:

• Required-field validation — implement in your handler; the relay forwards everything as-is so you control acceptance criteria.
• File size and type checks — Hooksbase enforces 15 MB per file and 50 MB per ingest; reject in your handler if the MIME type doesn't match expectations.
• Rate limiting — the relay's per-webhook ingest rate limit applies; for finer control, throttle by IP or session in your handler.
• CAPTCHA / proof-of-work — embed reCAPTCHA, Cloudflare Turnstile, or similar in the form; verify the token in your handler before processing.

The relay isn't a CAPTCHA service or a WAF. It is a reliable transport layer; the abuse-prevention belongs at the form's edge (CAPTCHA) and your handler's edge (validation).

Where to go next

• Let users trigger your agent through an embedded form for the practical Hooksbase setup walkthrough
• Email-to-webhook for AI agents for the email ingest channel
• Routing, transforms, and replay for AI agents for what to do once the form arrives
• How to build an AI agent for the full agent build path

Start free at app.hooksbase.com.