The config JSON

A form is defined by a single JSON document. It holds the fields, the validation rules, the emails to send, the webhooks to call, and a few settings. Everything about how a form behaves lives here, and it is stored as one value so it can never drift out of sync with itself.

You edit it either as raw JSON or through the structured editor. Both are views of the same document.

Top-level shape

{
  "fields":   [ /* the inputs the form accepts */ ],
  "email":    { /* notifications and autoresponders */ },
  "webhooks": [ /* endpoints to POST each submission to */ ],
  "settings": { /* submit label, thank-you screen, and more */ }
}

Only fields is required. Everything else is optional. Note that email is a single object, not an array, and webhooks is an array because a form can call several endpoints.

A complete example

Here is a contact form that emails you, sends the visitor a confirmation, and posts to a webhook:

{
  "fields": [
    { "name": "name",    "type": "text",     "label": "Your name", "rules": [{ "r": "required" }] },
    { "name": "email",   "type": "email",    "label": "Email",     "rules": [{ "r": "required" }, { "r": "email" }] },
    { "name": "phone",   "type": "tel",      "label": "Phone" },
    { "name": "message", "type": "textarea", "label": "Message",   "rules": [{ "r": "required" }, { "r": "max:2000" }] },
    { "name": "consent", "type": "checkbox", "label": "I agree to be contacted", "rules": [{ "r": "required" }] }
  ],
  "email": {
    "notification": {
      "enabled": true,
      "to": ["[email protected]"]
    },
    "confirmation": {
      "enabled": true,
      "toField": "email"
    }
  },
  "webhooks": [
    { "url": "https://hooks.example.com/octaforms", "active": true, "secret": "a-long-random-secret-at-least-32-chars" }
  ],
  "settings": {
    "submitLabel": "Send message",
    "thankYouTitle": "Thanks!",
    "thankYouText": "We will get back to you shortly."
  }
}

The sections

fields (required)

An array of the inputs your form accepts. Each field has at least a name and a type, usually a label, and optional validation rules. Field names must be unique.

{ "name": "email", "type": "text", "label": "Email", "rules": [{ "r": "required" }, { "r": "email" }] }

Every type and every option is covered in Field types. The rule format is covered in Validation rules.

Note

Only fields you declare here are accepted. If a submission carries a key you did not define, it is silently dropped. This keeps the data you store predictable.

email

Controls what gets sent when a submission arrives: a notification to you, and an optional confirmation to the person who submitted. Full details, including subjects, bodies and attachments, are on the Emails page.

webhooks

An array of endpoints that receive a signed POST for every submission. Each active webhook needs an https URL and a secret of at least 32 characters, used to sign the payload. See Webhooks.

settings

Small tweaks to how the form behaves:

Setting	Effect
submitLabel	Text on the submit button. Defaults to “Send”.
thankYouTitle and thankYouText	The success message shown after submitting. Both fall back to a translated default if left empty.
redirectUrl	If set, the visitor is redirected here after a successful submit instead of seeing the thank-you message. Takes priority over the thank-you text.
requireToken	Defaults to true. Set to false only as a last resort if a security plugin blocks the token endpoint. Honeypot and rate limiting stay active either way. See Anti-spam.

How it is stored and validated

The config is validated every time you save. Problems come in two kinds:

• Errors block the save. For example, a select field with no options, or an active webhook with a weak secret.
• Warnings let the save through but flag a risk. For example, a honeypot field with a name browsers tend to autofill.

Each problem is tied to the exact place it came from, so the editor can point you straight at it. On save, the previous version is kept, so the raw JSON editor offers a one-step undo.