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.io/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.io/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.

Deliveries are signed with the webhook secret of the account that owns the form. You don't need to create it first: if you don't have one yet, NueForm creates it when you open the Developer tab of your Profile, when you call GET /api/v1/webhooks/secret, or at the first delivery for one of your forms. You can regenerate it at any time in the same tab or with POST /api/v1/webhooks/secret.

See Verification for implementation details and code samples.

Secrets for Team Forms

Deliveries for a team form are signed with the team owner's secret, so verify them with that secret. NueForm doesn't create this one on its own: until the team owner has a secret, deliveries for the team's forms are skipped — nothing is sent and no failed attempt is recorded. The team owner creates it by opening the Developer tab of their Profile once, or by calling GET /api/v1/webhooks/secret with their own API key. The same call made with another member's API key creates that member's own secret, which team forms don't use.

Delivery Characteristics

Quick Start

To start receiving webhooks:

1. Get your webhook secret --- Open the Developer tab of your Profile, or call GET /api/v1/webhooks/secret. NueForm creates a secret if you don't have one yet. For a team form, use the team owner's secret (see Secrets for Team Forms).
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