Headless WordPress forms with Hatch

By the end of this guide you will know which forms plugins Hatch Connect works with, how a form built in WordPress shows up on your headless Astro frontend, where submissions are stored and how long Hatch keeps them.

Supported forms plugins

Hatch’s forms bridge reads forms from four providers:

• WPForms (Lite and Pro)
• Fluent Forms
• Gravity Forms
• Contact Form 7

If several are active, Hatch reports the first one it finds in this order: WPForms Pro, WPForms Lite, Fluent Forms, Gravity Forms, Contact Form 7. If none is installed, form features stay off.

How headless forms work in Hatch

No plugin CSS or JavaScript is sent to the frontend. Instead:

1. WordPress turns each provider’s form into a simple schema: a list of fields, a submit address and a nonce.
2. The Astro frontend draws its own form using your Hatch design.
3. When a visitor submits, the values are posted back to WordPress.
4. WordPress runs the form plugin’s own submission pipeline, so its validation, spam checks, notifications and confirmations still apply.

The bridge uses these addresses under /wp-json/hatch/v1/:

• GET /forms lists all detected forms.
• GET /forms/{provider}/{id} returns the schema for one form.
• POST /forms/{provider}/{id}/submit sends a submission.

Spam protection

• Every form includes a hidden honeypot field that real visitors never fill.
• Submissions are rate limited per visitor (10 attempts by default, changeable with the hatch_form_rate_limit filter).
• You can also switch on Cloudflare Turnstile. See Add Cloudflare Turnstile to WordPress forms.

Where submissions are stored

Some plugins, such as WPForms Lite, do not keep entries. So Hatch copies every submission from the frontend into its own table, wp_hatch_form_submissions (your table prefix may differ). Each row holds the field values, the form and provider name, the visitor’s IP address and browser user agent.

Behind Cloudflare, Hatch stores the real visitor IP only when you trust Cloudflare and the request comes from a Cloudflare edge. Otherwise it does not let a caller choose the stored address.

Older versions stored submissions as a private “Hatch Submissions” post type. That post type is still registered so those older entries stay readable under Tools in wp-admin.

90-day retention

1. Entries older than 90 days are deleted automatically.
2. The clean-up runs at most once a day, triggered by a new submission.
3. To change the period, use the hatch_form_retention_days filter. Returning 0 keeps every entry.

Hatch has no personal-data export or erasure tool for this table yet. To answer a data request, delete the matching rows from the table. Submissions and the table are kept on uninstall unless you tick “Remove all data on uninstall” in the Hatch settings first.

Check your forms

1. In wp-admin, open Hatch and go to the Plugins tab.
2. Confirm your forms plugin is detected.
3. Open /wp-json/hatch/v1/forms and check your forms are listed.
4. Send a test submission from the frontend and confirm the plugin’s notification arrives.

What to do next

• Add Cloudflare Turnstile to your forms
• Privacy and third-party services
• Security hardening
• Hatch endpoints reference