Webhooks im Überblick

Mit Webhooks erhält deine Anwendung HTTP-Benachrichtigungen in Echtzeit, sobald in NueForm etwas passiert. Statt die API nach neuen Antworten abzufragen, pusht NueForm die Daten an deinen Server, sobald ein Formular abgeschickt wird.

So funktionieren Webhooks

Wenn eine befragte Person ein Formular abschickt, sendet NueForm sofort eine HTTP-POST-Anfrage an jede von dir konfigurierte Webhook-URL. Der Anfrage-Body enthält eine signierte JSON-Payload mit dem Ereignistyp, den Formulardetails und den übermittelten Antworten.

Der Ablauf sieht so aus:

1. Eine befragte Person füllt dein Formular aus und schickt es ab.
2. NueForm validiert die Antworten und speichert die Response.
3. NueForm erstellt eine JSON-Payload mit den Ereignisdaten.
4. NueForm signiert die Payload mit deinem Webhook-Secret per HMAC-SHA256.
5. NueForm sendet die Payload als POST-Anfrage an jede konfigurierte URL.
6. Dein Server empfängt die Anfrage, prüft die Signatur und verarbeitet die Daten.

Die Webhook-Zustellung ist fire-and-forget und nicht blockierend. Fehlgeschlagene Webhooks beeinträchtigen niemals den Übermittlungsprozess --- Befragte sehen immer eine erfolgreiche Übermittlung, unabhängig davon, ob dein Webhook-Endpunkt erreichbar ist.

Webhooks pro Formular vs. globale Webhooks

NueForm unterstützt zwei Arten der Webhook-Konfiguration:

Webhooks pro Formular

Jedes Formular kann eine eigene Webhook-URL haben. Das ist praktisch, wenn verschiedene Formulare verschiedene Systeme benachrichtigen sollen --- zum Beispiel Support-Formulare an dein Helpdesk und Feedback-Formulare an deine Analytics-Pipeline.

Eine formularbezogene Webhook-URL kannst du auf zwei Wegen setzen:

• Über das NueForm-Dashboard --- Öffne die Einstellungen deines Formulars und trage die Webhook-URL ein.
• Über die API --- Nutze die Webhooks-API, um die URL programmatisch zu setzen oder zu aktualisieren.

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

Globale Webhooks

Globale Webhooks feuern bei jedem Formular in deinem Konto. Sie eignen sich für zentrales Logging, Analytics oder CRM-Integrationen, die alle Übermittlungen verarbeiten sollen — egal, aus welchem Formular sie stammen.

Du kannst bis zu 5 globale Webhooks konfigurieren, die sich einzeln aktivieren und deaktivieren lassen.

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

Zustellreihenfolge

Wird ein Formular abgeschickt, versendet NueForm die Webhooks parallel an alle zutreffenden URLs:

1. Die formularbezogene Webhook-URL (falls gesetzt).
2. Alle aktivierten globalen Webhook-URLs.

Jedes Ziel erhält dieselbe Payload mit derselben Signatur.

Wann Webhooks feuern

Aktuell feuern Webhooks bei genau einem Ereignis:

Bei Formularen mit aktivierter inkrementeller Übermittlung feuert der Webhook erst, wenn die Response als vollständig markiert ist --- Zwischenspeicherungen lösen keine Webhooks aus.

Die vollständige Ereignisreferenz und geplante zukünftige Ereignisse findest du unter Ereignisse.

Webhook-Sicherheit

Jede Webhook-Anfrage enthält einen X-NueForm-Signature-Header mit einem HMAC-SHA256-Hex-Digest des Anfrage-Bodys. Du solltest diese Signatur immer prüfen, bevor du Webhook-Daten verarbeitest, um sicherzustellen, dass die Anfrage wirklich von NueForm stammt.

Zustellungen werden mit dem Webhook-Secret des Kontos signiert, dem das Formular gehört. Du musst es nicht vorher anlegen: Hast du noch keines, erstellt NueForm es, wenn du den Tab Entwickler in deinem Profil öffnest, wenn du GET /api/v1/webhooks/secret aufrufst oder bei der ersten Zustellung für eines deiner Formulare. Du kannst es jederzeit im selben Tab oder mit POST /api/v1/webhooks/secret neu erzeugen.

Implementierungsdetails und Codebeispiele findest du unter Verifizierung.

Secrets für Team-Formulare

Zustellungen für ein Team-Formular werden mit dem Secret des Team-Eigentümers signiert – prüfe sie also mit diesem Secret. NueForm erstellt es nicht von selbst: Solange der Team-Eigentümer kein Secret hat, werden Zustellungen für die Formulare des Teams übersprungen – es wird nichts gesendet und kein fehlgeschlagener Versuch protokolliert. Der Team-Eigentümer erstellt es, indem er einmal den Tab Entwickler in seinem Profil öffnet oder GET /api/v1/webhooks/secret mit seinem eigenen API-Schlüssel aufruft. Derselbe Aufruf mit dem API-Schlüssel eines anderen Mitglieds erstellt dessen eigenes Secret, das Team-Formulare nicht verwenden.

Zustellungseigenschaften

Schnellstart

So empfängst du deine ersten Webhooks:

1. Hole dir dein Webhook-Secret --- Öffne den Tab Entwickler in deinem Profil oder rufe GET /api/v1/webhooks/secret auf. NueForm erstellt ein Secret, falls du noch keines hast. Für ein Team-Formular verwendest du das Secret des Team-Eigentümers (siehe Secrets für Team-Formulare).
2. Richte eine Webhook-URL ein --- Konfiguriere eine formularbezogene URL oder füge einen globalen Webhook hinzu.
3. Implementiere deinen Endpunkt --- Baue einen HTTP-Endpunkt, der POST-Anfragen entgegennimmt, die Signatur prüft und die Payload verarbeitet.
4. Teste ihn --- Nutze ein Tool wie webhook.site oder ngrok, um die Zustellung vor dem Produktivbetrieb zu prüfen. Eine ausführliche Anleitung findest du unter Webhooks testen.

Nächste Schritte

• Ereignisse --- Lerne die Webhook-Ereignistypen kennen
• Payloads --- Sieh dir das vollständige Payload-Schema und Beispiele an
• Verifizierung --- Implementiere die HMAC-SHA256-Signaturprüfung
• Testen --- Teste Webhooks in der lokalen Entwicklung