Form Ingest

Form ingest turns a webhook into a browser-friendly submission endpoint. It is useful for lightweight embeds, back-office tools, or systems that can only post traditional HTML forms instead of signed JSON requests.

Form channel model

The public form URL follows this shape:

https://hooks.hooksbase.com/v1/form/{publicId}

The webhook's publicId (hook_...) is returned in the create-webhook response as formIngestUrl. No separate secret is required — the unguessable publicId is the access credential, so rotate the webhook if the URL leaks.

The endpoint supports both:

  • a minimal HTML form page (GET) for quick testing or lightweight embeds
  • real form submissions (POST) that become deliveries on the target webhook

Auth model

  • Name
    Public form route
    Description

    GET, POST, and OPTIONS on /v1/form/{publicId} are public. The route relies on the unguessable publicId.

  • Name
    Dashboard
    Description

    There is no separate dashboard-only form runtime. You create or inspect the webhook through the normal webhook surfaces and then publish the form URL.

  • Name
    SDK / CLI
    Description

    The first-party SDK and CLI do not expose form-specific helpers yet.

Content types and CORS

Supported request content types are:

  • application/x-www-form-urlencoded
  • multipart/form-data

Anything else returns 415.

POST and OPTIONS responses on the form route send permissive CORS headers:

  • Access-Control-Allow-Origin: *
  • Access-Control-Allow-Methods: POST, OPTIONS
  • Access-Control-Allow-Headers: Content-Type

Use OPTIONS /v1/form/{publicId} for preflight requests.

Payloads and files

Hooksbase normalizes the submission into a JSON envelope:

  • source: "form"
  • fields for scalar and multi-value form fields
  • optional files for uploads

Field coercion rules:

  • a single submitted value stays a string
  • repeated field names become arrays

File behavior:

  • per-file limit: 15 MB
  • per-ingest total: 50 MB
  • when file storage is available, each file gets a fileRef
  • free-tier projects keep file metadata only

Status behavior follows normal ingest:

  • 404 for archived or missing webhooks
  • 409 for paused webhooks or disabled projects
  • GET /v1/form/{publicId}
  • POST /v1/form/{publicId}
  • OPTIONS /v1/form/{publicId}
  • GET /v1/files/{signedToken}
  • GET /v1/webhooks/{webhookId}/deliveries/{deliveryId}/files/{index}

Common mistakes

  • Treating the form endpoint like a general JSON ingest route. It only accepts classic form content types.
  • Forgetting to handle repeated field names as arrays.
  • Assuming browser uploads bypass the same webhook paused and project-disabled checks as other ingest channels.
  • Expecting file content persistence on the free tier, where only metadata is retained.

Was this page helpful?