How it works

The request lifecycle, the objects you work with, and who can do what.

Request lifecycle#

1. Loading a form#

f2wf.load(org, form) requests the form's public config from form2wf. The response contains the fields and layout but never your webhook URLs or header secrets. If the form requires login, the widget checks the visitor's session first (see Who can use a form). If the form has an onload webhook, the widget then calls it through form2wf and uses the response to fill fields and tables.

2. Submitting#

The widget posts the values to /api/v1/submit/<form-id>. form2wf checks the form is active, the visitor is allowed, and your monthly quota has room, then forwards the data to your submit webhook with your configured headers. n8n has 30 seconds to answer. Any 2xx reply is a success; the visitor sees your success message.

3. Buttons and row actions#

Buttons and table row actions call webhooks you configured on the field. The browser only sends which button was clicked — the URL, method and headers always come from the stored form, so a visitor can't redirect a call elsewhere.

Objects#

Object	Belongs to	Key facts
Organization	—	Has a plan (quotas), team members, a slug used in public URLs.
Form	Organization	UUID `id` (used by the submit API and SDK) and `slug` (used in embed snippets and hosted URLs). Settings + `config` JSON.
Folder	Organization	Dashboard organization only. Deleting a folder keeps its forms.
Submission	Form	Logged for every attempt with status and n8n response.
Theme	Organization	Colors and spacing, applied through `config.theme_id`.
Form user / role	Organization	Who may use Protected forms.
API key	Organization	Access for AI agents through MCP; acts as the member who created it.

Team roles#

Capability	User	Creator	Admin	Owner
View forms, submissions, usage	Yes	Yes	Yes	Yes
Create and edit forms and folders	—	Yes	Yes	Yes
Delete forms, form access, themes, roles, form users	—	—	Yes	Yes
Invite and manage team, API keys, billing checkout	—	—	Yes	Yes
Change plan, cancel, transfer ownership	—	—	—	Yes

API keys map onto these roles: a viewer key acts as a user, editor as a creator, admin as an admin — never higher than the role of the member who created it.

IDs vs slugs#

Embed snippets, hosted pages, navigation targets and targetForm use the form slug. The submit/fetch API, the SDK and MCP tools use the form UUID. Changing a slug breaks existing embeds and links to it; the UUID never changes.