Webhooks API

Configure per-form and global webhooks for real-time response notifications.

Webhooks let you receive real-time HTTP POST notifications when forms receive new submissions. NueForm supports two levels of webhooks:

Form webhooks -- A single URL per form that receives submissions for that specific form.
Global webhooks -- Up to 5 URLs that receive submissions from all of your forms.

Webhooks require a Pro plan or higher. Attempting to use webhook endpoints on a free plan will return a 403 error.

All request and response bodies use snake_case field names.

Endpoints

GET/api/v1/forms/:id/webhooksPUT/api/v1/forms/:id/webhooksGET/api/v1/webhooksPUT/api/v1/webhooksGET/api/v1/webhooks/secretPOST/api/v1/webhooks/secret

Get Form Webhook

GET/api/v1/forms/:id/webhooks

Retrieves the webhook URL configured for a specific form.

Path Parameters

idstringrequired

The form ID

If no webhook is configured, webhook_url will be null.

Response

json

{
  "webhook_url": "https://example.com/hooks/nueform"
}

Code Examples

bash

curl -X GET "https://api.nueform.io/api/v1/forms/665a1b2c3d4e5f6a7b8c9d0e/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY"

Set Form Webhook

PUT/api/v1/forms/:id/webhooks

Sets or clears the webhook URL for a specific form. When a submission is received, NueForm will send an HTTP POST to this URL with the response data.

Path Parameters

idstringrequired

The form ID

Request Body

urlstring or nullrequired

The webhook URL. Must be a valid URL. Set to null to remove the webhook.

Request Example

json

{
  "url": "https://example.com/hooks/nueform"
}

To remove a webhook:

json

{
  "url": null
}

Response

json

{
  "webhook_url": "https://example.com/hooks/nueform"
}

Code Examples

bash

curl -X PUT "https://api.nueform.io/api/v1/forms/665a1b2c3d4e5f6a7b8c9d0e/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/hooks/nueform" }'

List Global Webhooks

GET/api/v1/webhooks

Retrieves all global webhooks configured for your account. Global webhooks fire for every form submission across all of your forms.

Response

json

{
  "webhooks": [
    {
      "url": "https://example.com/hooks/all-forms",
      "enabled": true
    },
    {
      "url": "https://backup.example.com/hooks/nueform",
      "enabled": false
    }
  ]
}

Code Examples

bash

curl -X GET "https://api.nueform.io/api/v1/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY"

Set Global Webhooks

PUT/api/v1/webhooks

Replaces all global webhooks with the provided array. You can configure up to 5 global webhooks. Each webhook can be individually enabled or disabled.

Request Body

webhooksarrayrequired

Array of webhook objects (max 5)

Request Example

json

{
  "webhooks": [
    {
      "url": "https://example.com/hooks/all-forms",
      "enabled": true
    },
    {
      "url": "https://slack-webhook.example.com/nueform",
      "enabled": true
    },
    {
      "url": "https://backup.example.com/hooks/nueform",
      "enabled": false
    }
  ]
}

Response

json

{
  "webhooks": [
    {
      "url": "https://example.com/hooks/all-forms",
      "enabled": true
    },
    {
      "url": "https://slack-webhook.example.com/nueform",
      "enabled": true
    },
    {
      "url": "https://backup.example.com/hooks/nueform",
      "enabled": false
    }
  ]
}

Code Examples

bash

curl -X PUT "https://api.nueform.io/api/v1/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhooks": [
      { "url": "https://example.com/hooks/all-forms", "enabled": true },
      { "url": "https://backup.example.com/hooks/nueform", "enabled": false }
    ]
  }'

Get Webhook Secret

GET/api/v1/webhooks/secret

Retrieves your webhook signing secret. If no secret exists yet, one is automatically generated. The secret is a 64-character hex string derived from 32 random bytes.

Use this secret to verify that incoming webhook requests are genuinely from NueForm by validating the HMAC-SHA256 signature in the X-NueForm-Signature header.

Verifying Signatures

When NueForm sends a webhook, it includes an X-NueForm-Signature header containing an HMAC-SHA256 hex digest of the request body. Verify it in your webhook handler to ensure authenticity.

Response

json

{
  "secret": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2"
}

Signature Verification Examples

javascript

const crypto = require("crypto");

function verifyWebhookSignature(body, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Code Examples

bash

curl -X GET "https://api.nueform.io/api/v1/webhooks/secret" \
  -H "Authorization: Bearer YOUR_API_KEY"

Regenerate Webhook Secret

POST/api/v1/webhooks/secret

Generates a new webhook signing secret, replacing the existing one. After regeneration, all webhook deliveries will be signed with the new secret.

After regenerating, update your webhook receivers immediately to use the new secret. Requests signed with the old secret will fail verification.

Response

json

{
  "secret": "f0e1d2c3b4a5968778695a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d"
}

Code Examples

bash

curl -X POST "https://api.nueform.io/api/v1/webhooks/secret" \
  -H "Authorization: Bearer YOUR_API_KEY"

Webhook Payload Format

When a form receives a submission, NueForm sends a POST request to your configured webhook URLs with the following payload.

The event field identifies the event type, and the response object contains the full submission data including all answers.

Headers

Content-Typeapplication/json

Request body content type

X-NueForm-Signaturestring

HMAC-SHA256 hex digest of the request body

X-NueForm-Eventstring

Event type (e.g., response.submitted)

Payload Example

json

{
  "event": "response.submitted",
  "form_id": "665a1b2c3d4e5f6a7b8c9d0e",
  "form_title": "Customer Feedback Survey",
  "response": {
    "id": "667a1b2c3d4e5f6a7b8c9d01",
    "submitted_at": "2026-02-27T15:42:00.000Z",
    "completed_at": "2026-02-27T15:45:30.000Z",
    "answers": [
      {
        "question_id": "66a1b2c3d4e5f6a7b8c9d001",
        "question_title": "What is your name?",
        "value": "Jane Smith"
      }
    ]
  }
}

Error Responses

Standard error responses returned by webhook endpoints.

Error Codes

400Bad Request

Invalid URL format, exceeded max 5 global webhooks, or missing required fields

401Unauthorized

Missing or invalid API key

403Forbidden

Webhooks require a Pro plan or higher

404Not Found

Form not found

500Server Error

Internal server error

Error Example

json

{
  "error": "Webhooks require a Pro plan or higher"
}

Last updated: May 23, 2026