Webhooks - FormFlow Docs
Deploy complex forms instantly
Webhook Configuration Setup
How to configure webhooks for real-time data pushing.
Navigate to your FormFlow dashboard, select the target form, and open the Integrations panel. Enter your secure HTTPS endpoint URL in the designated field. FormFlow validates SSL certificates automatically and requires a 200–299 HTTP status code to confirm successful delivery. You can attach up to three distinct endpoints per form, routing submissions to your CRM, data warehouse, or custom Slack listener.
Generate Signature Secret
Click the lock icon next to the URL input to auto-generate a 32-character HMAC-SHA256 secret. Store this in your environment variables to verify incoming requests.
Map Form Fields to Routes
Use the toggle switches to include or exclude specific fields like `customer_email`, `order_total`, or `compliance_consent` from the outbound payload.
Activate & Monitor
Flip the master switch to green. Real-time delivery logs appear in the Activity tab, showing latency, status codes, and raw request/response pairs.
JSON Payload Structure
JSON payload structure and error handling/retry logic.
Every outbound webhook delivers a standardized JSON object wrapped in a `formflow_event` envelope. The payload includes metadata about the submission, the form configuration version, and the exact field values captured at runtime.
Event Headers & IDs
Each payload ships with `event_id` (UUID v4), `timestamp` (ISO 8601), `form_id` (e.g., `ff_9a8b7c6d`), and `webhook_id`. The `X-FormFlow-Signature` header contains the HMAC hash for verification.
Field Mapping & Types
Nested objects preserve your form structure. A multi-step form named `Enterprise Onboarding Q3` will output `step_1.employee_name`, `step_2.department_code`, and `step_3.attachment_url`. Dates serialize as `YYYY-MM-DD`, and currency fields strip locale formatting.
Hidden & Computed Fields
Fields marked as hidden via conditional logic still appear in the payload if they triggered a branch. Computed totals like `tax_amount` and `discount_code` are included automatically when enabled in the form builder.
Error Handling & Retry Logic
Automatic fallback mechanisms for failed deliveries.
FormFlow implements an exponential backoff strategy to ensure critical submission data reaches your infrastructure without overwhelming your servers. Failed requests are queued and retried based on HTTP status codes and response timeouts.
5xx Errors & Timeouts
Endpoints returning 500–599 or failing to respond within 5 seconds trigger immediate retries. FormFlow attempts delivery at 1 minute, 5 minutes, 30 minutes, and 2 hours before marking the event as permanently failed.
4xx Responses & Validation
400–499 status codes halt retries instantly. FormFlow logs the exact error body in the webhook dashboard. Common causes include malformed JSON parsing, missing required headers, or expired SSL certificates on your receiving domain.
Manual Replay & Export
After four failed attempts, payloads move to the Dead Letter Queue. You can manually replay individual events, export failed batches as CSV, or configure a fallback endpoint to catch orphaned submissions.