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

Dein Webhook-Secret wird beim ersten Zugriff automatisch generiert und kann jederzeit über die API oder das Dashboard neu erzeugt werden.

Implementierungsdetails und Codebeispiele findest du unter Verifizierung.

Zustellungseigenschaften

Schnellstart

So empfängst du deine ersten Webhooks:

1. Hole dir dein Webhook-Secret --- Rufe GET /api/v1/webhooks/secret auf oder finde es im Dashboard unter den Developer-Einstellungen. NueForm generiert automatisch ein Secret, falls du noch keines hast.
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