Webhooks

Webhooks allow you to automatically send form submission data to external services, APIs, or your own backend whenever a new submission is received.

Use Cases: CRM integrations, custom workflows, database syncing, and more.

---

Setup

1. Go to your Form Settings
2. Navigate to Actions → Webhook
3. Enter your webhook endpoint URL
4. Save changes

Once configured, Forminit will automatically POST submission data to your endpoint URL whenever a new form submission is received.

---

Webhook Payload

When a form is submitted, Forminit sends a POST request to your webhook URL with a JSON payload containing the submission data.

Example Payload

{
  "event": "form.submitted",
  "formName": "contact-form",
  "id": "xK9mLpQr2vNtYw8z",
  "submissionStatus": "Open",
  "data": {
    "message": "I'm interested in learning more about your enterprise solutions.",
    "sender": {
      "email": "james.wilson@example.co.uk",
      "firstName": "James",
      "lastName": "Wilson",
      "phone": "+442071234567",
      "company": "Acme Ltd",
      "position": "Product Manager"
    },
    "plan": "Enterprise",
    "budget": 50000,
    "preferred-date": "2026-02-15",
    "file-proposal": {
      "file": "https://files.forminit.com/abc123/project-proposal.pdf",
      "size": 245000,
      "name": "project-proposal.pdf"
    },
    "file-attachments": [
      {
        "file": "https://files.forminit.com/abc123/requirements.pdf",
        "size": 128400,
        "name": "requirements.pdf"
      },
      {
        "file": "https://files.forminit.com/abc123/timeline.xlsx",
        "size": 45200,
        "name": "timeline.xlsx"
      }
    ],
    "submissionDate": "05-01-2026 14:30",
    "submissionDateISO": "2026-01-05T14:30:00+00:00",
    "submission_info": {
      "ip": "203.0.113.42",
      "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36",
      "referer": "https://example.co.uk/contact",
      "sdk_version": "0.2.1",
      "location": {
        "country": {
          "name": "United Kingdom",
          "iso": "GB"
        },
        "city": {
          "name": "London"
        },
        "geo": {
          "lat": 51.5074,
          "lng": -0.1278
        },
        "timezone": "Europe/London"
      }
    }
  }
}

---

Payload Structure

Top-Level Fields

Field	Type	Description
event	string	Event type. Always form.submitted for new submissions
formName	string	Name of the form that received the submission
id	string	Unique submission identifier
submissionStatus	string	Current status of the submission (Open, Closed, etc.)
data	object	Contains all submitted form data and metadata

Data Object

The data object contains all form field values using their field names as keys.

Field	Type	Description
sender	object	Submitter information (email, name, phone, etc.)
{field-name}	varies	Values from single blocks (text, number, select, etc.)
file-{name}	object/array	File upload data (single file or array of files)
submissionDate	string	Human-readable submission date (DD-MM-YYYY HH:mm)
submissionDateISO	string	ISO 8601 formatted submission timestamp
submission_info	object	Technical metadata about the submission

Sender Object

Field	Type	Description
email	string	Submitter’s email address
firstName	string	Submitter’s first name
lastName	string	Submitter’s last name
fullName	string	Submitter’s full name (if collected as single field)
phone	string	Phone number in E.164 format
company	string	Company or organization
position	string	Job title or position
address	string	Street address
city	string	City name
country	string	ISO 3166-1 alpha-2 country code

File Object

Single file uploads return an object. Multiple file uploads return an array of objects.

Field	Type	Description
file	string	Public URL to download the file
name	string	Original filename
size	number	File size in bytes

Submission Info Object

Field	Type	Description
ip	string	Submitter’s IP address
user_agent	string	Browser user agent string
referer	string	Page URL where form was submitted
sdk_version	string	Forminit SDK version (if using SDK)
location	object	Geolocation data derived from IP

Location Object

Field	Type	Description
country.name	string	Country name
country.iso	string	ISO 3166-1 alpha-2 country code
city.name	string	City name
geo.lat	number	Latitude coordinate
geo.lng	number	Longitude coordinate
timezone	string	IANA timezone identifier

---

Handling Webhooks

Your webhook endpoint should:

1. Accept POST requests with Content-Type: application/json
2. Return a 2xx status code to acknowledge receipt
3. Process the request within 30 seconds

Example: Node.js/Express

app.post('/webhook/forminit', express.json(), (req, res) => {
  const { event, formName, id, data } = req.body;
  
  if (event === 'form.submitted') {
    console.log(`New submission from ${data.sender?.email}`);
    // Process the submission...
  }
  
  res.status(200).json({ received: true });
});

Example: Next.js API Route

// app/api/webhook/forminit/route.ts
import { NextResponse } from 'next/server';

export async function POST(request: Request) {
  const payload = await request.json();
  const { event, formName, id, data } = payload;
  
  if (event === 'form.submitted') {
    // Process the submission...
    console.log(`New submission: ${id}`);
  }
  
  return NextResponse.json({ received: true });
}

---

Testing Webhooks

Use webhook.site to test your webhook integration:

1. Go to webhook.site and copy your unique URL
2. Add the URL to your form’s webhook settings
3. Submit a test form entry
4. View the payload in webhook.site

---

Retry Policy

If your endpoint returns a non-2xx status code or times out, Forminit will retry the webhook delivery with exponential backoff.