Aperçu des Webhooks

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.

Sécurité des webhooks

Chaque requête de webhook contient un en-tête X-NueForm-Signature avec un condensé hexadécimal HMAC-SHA256 du corps de la requête. Vérifiez toujours cette signature avant de traiter les données d'un webhook, pour vous assurer que la requête vient bien de NueForm.

Les envois sont signés avec le secret de webhook du compte propriétaire du formulaire. Vous n'avez pas besoin de le créer à l'avance : si vous n'en avez pas encore, NueForm le crée quand vous ouvrez l'onglet Développeur de votre Profil, quand vous appelez GET /api/v1/webhooks/secret, ou lors du premier envoi pour l'un de vos formulaires. Vous pouvez le régénérer à tout moment dans ce même onglet ou avec POST /api/v1/webhooks/secret.

Consultez Vérification pour les détails d'implémentation et des exemples de code.

Secrets des formulaires d'équipe

Les envois d'un formulaire d'équipe sont signés avec le secret du propriétaire de l'équipe : vérifiez-les donc avec ce secret. NueForm ne le crée pas de lui-même : tant que le propriétaire de l'équipe n'a pas de secret, les envois des formulaires de l'équipe sont ignorés — rien n'est envoyé et aucune tentative échouée n'est enregistrée. Le propriétaire de l'équipe le crée en ouvrant une fois l'onglet Développeur de son Profil, ou en appelant GET /api/v1/webhooks/secret avec sa propre clé d'API. Le même appel fait avec la clé d'API d'un autre membre crée le secret de ce membre, que les formulaires d'équipe n'utilisent pas.

Delivery Characteristics

Quick Start

To start receiving webhooks:

1. Obtenez votre secret de webhook --- Ouvrez l'onglet Développeur de votre Profil, ou appelez GET /api/v1/webhooks/secret. NueForm crée un secret si vous n'en avez pas encore. Pour un formulaire d'équipe, utilisez le secret du propriétaire de l'équipe (voir Secrets des formulaires d'équipe).
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