Webhooks-API

Konfiguriere formularspezifische und globale Webhooks für Echtzeit-Benachrichtigungen über Antworten.

Mit Webhooks erhältst du in Echtzeit HTTP-POST-Benachrichtigungen, wenn Formulare neue Übermittlungen empfangen. NueForm unterstützt zwei Ebenen von Webhooks:

Formular-Webhooks — Eine einzelne URL pro Formular, die Übermittlungen für dieses spezifische Formular empfängt.
Globale Webhooks — Bis zu 5 URLs, die Übermittlungen von all deinen Formularen empfangen.

Webhooks erfordern einen Pro-Plan oder höher. Der Versuch, Webhook-Endpunkte in einem kostenlosen Plan zu nutzen, gibt einen 403-Fehler zurück.

Alle Request- und Antwort-Bodys verwenden Feldnamen in snake_case.

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

Formular-Webhook abrufen

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

Ruft die für ein bestimmtes Formular konfigurierte Webhook-URL ab.

Pfad-Parameter

idstringerforderlich

Die Formular-ID

Ist kein Webhook konfiguriert, ist webhook_url gleich null.

Antwort

json

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

Codebeispiele

bash

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

Formular-Webhook setzen

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

Setzt oder entfernt die Webhook-URL für ein bestimmtes Formular. Bei Eingang einer Übermittlung sendet NueForm einen HTTP POST mit den Antwortdaten an diese URL.

Pfad-Parameter

idstringerforderlich

Die Formular-ID

Request-Body

urlstring or nullerforderlich

Die Webhook-URL. Muss eine gültige URL sein. Setze null, um den Webhook zu entfernen.

Request-Beispiel

json

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

So entfernst du einen Webhook:

json

{
  "url": null
}

Antwort

json

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

Codebeispiele

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" }'

Globale Webhooks auflisten

GET/api/v1/webhooks

Ruft alle für dein Konto konfigurierten globalen Webhooks ab. Globale Webhooks feuern bei jeder Formularübermittlung über alle deine Formulare hinweg.

Antwort

json

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

Codebeispiele

bash

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

Globale Webhooks setzen

PUT/api/v1/webhooks

Ersetzt alle globalen Webhooks durch das übergebene Array. Du kannst bis zu 5 globale Webhooks konfigurieren. Jeder Webhook kann einzeln aktiviert oder deaktiviert werden.

Request-Body

webhooksarrayerforderlich

Array von Webhook-Objekten (max. 5)

Request-Beispiel

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
    }
  ]
}

Antwort

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
    }
  ]
}

Codebeispiele

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 }
    ]
  }'

Webhook-Secret abrufen

GET/api/v1/webhooks/secret

Ruft dein Webhook-Signatur-Secret ab. Existiert noch kein Secret, wird automatisch eines generiert. Das Secret ist ein 64-stelliger Hex-String, abgeleitet aus 32 Zufallsbytes.

Verwende dieses Secret, um zu verifizieren, dass eingehende Webhook-Requests wirklich von NueForm stammen, indem du die HMAC-SHA256-Signatur im Header X-NueForm-Signature validierst.

Wenn NueForm einen Webhook sendet, enthält er einen X-NueForm-Signature-Header mit einem HMAC-SHA256-Hex-Digest des Request-Bodys. Verifiziere ihn in deinem Webhook-Handler, um die Echtheit sicherzustellen.

Antwort

json

{
  "secret": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2"
}

Beispiele zur Signaturverifizierung

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)
  );
}

Codebeispiele

bash

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

Webhook-Secret neu generieren

POST/api/v1/webhooks/secret

Generiert ein neues Webhook-Signatur-Secret und ersetzt das bestehende. Nach der Neugenerierung werden alle Webhook-Zustellungen mit dem neuen Secret signiert.

Aktualisiere nach der Neugenerierung sofort deine Webhook-Empfänger auf das neue Secret. Requests, die mit dem alten Secret signiert wurden, schlagen bei der Verifizierung fehl.

Antwort

json

{
  "secret": "f0e1d2c3b4a5968778695a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d"
}

Codebeispiele

bash

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

Webhook-Payload-Format

Wenn ein Formular eine Übermittlung erhält, sendet NueForm einen POST-Request mit folgendem Payload an deine konfigurierten Webhook-URLs.

Das Feld event identifiziert den Ereignistyp, und das response-Objekt enthält die vollständigen Übermittlungsdaten inklusive aller Antworten.

Header

Content-Typeapplication/json

Content-Type des Request-Bodys

X-NueForm-Signaturestring

HMAC-SHA256-Hex-Digest des Request-Bodys

X-NueForm-Eventstring

Ereignistyp (z. B. response.submitted)

Payload-Beispiel

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"
      }
    ]
  }
}

Fehlerantworten

Standard-Fehlerantworten, die Webhook-Endpunkte zurückgeben.

Fehlercodes

400Bad Request

Ungültiges URL-Format, mehr als 5 globale Webhooks oder fehlende Pflichtfelder

401Unauthorized

Fehlender oder ungültiger API-Schlüssel

403Forbidden

Webhooks erfordern einen Pro-Plan oder höher

404Not Found

Formular nicht gefunden

500Server Error

Interner Serverfehler

Fehlerbeispiel

json

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

Zuletzt aktualisiert: 20. Juli 2026