Webhooks Guide - FormFlow

Enterprise-grade forms, zero code required. Push real-time form data directly to your systems.

Trigger Events

Available Webhook Triggers

Configure your endpoints to listen for specific lifecycle events. FormFlow fires payloads immediately upon state changes, ensuring your CRM, ERP, or custom database stays synchronized without polling.

form_submitted

Dispatched when a respondent completes and submits a form. Includes all field values, respondent metadata, and submission timestamps.

payment_received

Triggered upon successful checkout or invoice settlement. Contains transaction ID, amount, currency, and Stripe/PayPal gateway reference.

form_published

Fires when a draft form transitions to a live state. Useful for syncing form schemas to your internal documentation or analytics dashboards.

Payload Structure

Standard JSON Schema

Every webhook delivers a consistent envelope. The top-level object contains routing metadata, while the nested data object holds the form-specific content.

Example payload for a form_submitted event:

{
  "event_id": "evt_8f3a9b2c1d",
  "event_type": "form_submitted",
  "timestamp": "2024-05-12T14:30:00Z",
  "form_id": "frm_9x7k2m",
  "data": {
    "submission_id": "sub_4j8n1p",
    "fields": [
      { "name": "full_name", "value": "Elena Rodriguez" },
      { "name": "company_email", "value": "elena@nexuslogistics.com" },
      { "name": "service_tier", "value": "enterprise" }
    ],
    "ip_address": "203.0.113.42",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)"
  }
}

Note: Array fields and conditional logic branches are flattened into the fields array for predictable parsing. Null values are omitted entirely to reduce payload size.

Security & Verification

Verifying Signatures

Protect your endpoints from spoofed requests. FormFlow signs every payload using HMAC-SHA256 with your unique webhook secret. Always validate the signature before processing data.

Verification steps:

  1. Extract the x-formflow-signature header from the incoming request.
  2. Concatenate the raw request body with your webhook secret.
  3. Generate an HMAC-SHA256 hash and compare it against the header value using a constant-time comparison function.

If the signatures mismatch, return a 401 Unauthorized status. Valid requests receive a 200 OK response within 500ms to prevent retry queues from triggering. For production environments, rotate your webhook secrets quarterly via the Developer Console under Settings > API & Integrations.