Webhooks Overview

Webhooks let your application receive real-time HTTP notifications whenever something happens in NueForm. Instead of polling the API for new responses, NueForm pushes data to your server the moment a form is submitted.

How Webhooks Work

When a respondent submits a form, NueForm immediately sends an HTTP POST request to every webhook URL you have configured. The request body contains a signed JSON payload with the event type, form details, and the submitted answers.

The flow looks like this:

1. A respondent completes and submits your form.
2. NueForm validates the answers and stores the response.
3. NueForm constructs a JSON payload containing the event data.
4. NueForm signs the payload with your webhook secret using HMAC-SHA256.
5. NueForm sends the payload as a POST request to each configured URL.
6. Your server receives the request, verifies the signature, and processes the data.

Webhook delivery is fire-and-forget and non-blocking. Webhook failures never affect the submission flow --- respondents always see a successful submission regardless of whether your webhook endpoint is reachable.

Per-Form vs. Global Webhooks

NueForm supports two types of webhook configuration:

Per-Form Webhooks

Each form can have its own dedicated webhook URL. This is useful when you want different forms to notify different systems --- for example, sending support form submissions to your helpdesk and feedback form submissions to your analytics pipeline.

You can set a per-form webhook URL through:

• The NueForm Dashboard --- Open your form's settings and enter the webhook URL.
• The API --- Use the Webhooks API to set or update the URL programmatically.

curl -X PUT https://app.nueform.com/api/v1/webhooks/form/FORM_ID \
  -H "Authorization: Bearer nf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://your-server.com/webhooks/nueform" }'

Global Webhooks

Global webhooks fire for every form in your account. They are useful for centralized logging, analytics, or CRM integrations that need to process all submissions regardless of which form they came from.

You can configure up to 5 global webhooks, and each one can be individually enabled or disabled.

curl -X PUT https://app.nueform.com/api/v1/webhooks/global \
  -H "Authorization: Bearer nf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "webhooks": [
      { "url": "https://analytics.example.com/nueform", "enabled": true },
      { "url": "https://crm.example.com/inbound", "enabled": true },
      { "url": "https://staging.example.com/test", "enabled": false }
    ]
  }'

Delivery Order

When a form is submitted, NueForm dispatches webhooks to all applicable URLs in parallel:

1. The form's per-form webhook URL (if set).
2. All enabled global webhook URLs.

Every target receives the same payload with the same signature.

When Webhooks Fire

Currently, webhooks fire on a single event:

For forms with incremental submission enabled, the webhook fires only when the response is marked as complete --- partial saves do not trigger webhooks.

See Events for the full event reference and planned future events.

Webhook Security

Every webhook request includes an X-NueForm-Signature header containing an HMAC-SHA256 hex digest of the request body. You should always verify this signature before processing webhook data to ensure the request genuinely came from NueForm.

Your webhook secret is automatically generated the first time you access it and can be regenerated at any time via the API or dashboard.

See Verification for implementation details and code samples.

Delivery Characteristics

Quick Start

To start receiving webhooks:

1. Get your webhook secret --- Call GET /api/v1/webhooks/secret or find it in your dashboard under Developer settings. NueForm auto-generates a secret if you do not have one yet.
2. Set up a webhook URL --- Configure a per-form URL or add a global webhook.
3. Implement your endpoint --- Build an HTTP endpoint that accepts POST requests, verifies the signature, and processes the payload.
4. Test it --- Use a tool like webhook.site or ngrok to verify delivery before going to production. See Testing Webhooks for detailed instructions.

Next Steps

• Events --- Learn about webhook event types
• Payloads --- See the full payload schema and examples
• Verification --- Implement HMAC-SHA256 signature verification
• Testing --- Test webhooks during local development