Webhooks testen

Um Webhooks während der Entwicklung zu testen, muss dein Endpunkt aus dem öffentlichen Internet erreichbar sein. Diese Anleitung stellt mehrere Ansätze vor — von schnellen Inspektionstools bis zum vollständigen lokalen Entwicklungssetup.

Option 1: webhook.site (schnelle Inspektion)

webhook.site stellt eine temporäre öffentliche URL bereit, die eingehende HTTP-Anfragen erfasst und anzeigt. Das ist der schnellste Weg zu sehen, was NueForm sendet, ohne Code zu schreiben.

Gehe auf webhook.site.
Kopiere die eindeutige URL (z. B. https://webhook.site/abc123-def456-...).
Setze sie als Webhook-URL deines Formulars:

bash

curl -X PUT https://app.nueform.com/api/v1/webhooks/form/YOUR_FORM_ID \
  -H "Authorization: Bearer nf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://webhook.site/abc123-def456-..." }'

Übermittle eine Antwort auf dein Formular.
Aktualisiere webhook.site, um die erfasste Anfrage zu sehen — inklusive Header, Body und der X-NueForm-Signature.

webhook.site eignet sich hervorragend zur Inspektion, erlaubt aber keine eigene Verifizierungslogik. Nutze es, um das Payload-Format zu verstehen, und wechsle dann für vollständige Tests zu einem lokalen Server.

Option 2: ngrok (lokale Entwicklung)

ngrok erstellt einen sicheren Tunnel von einer öffentlichen URL zu deinem lokalen Rechner. So empfängst du echte Webhook-Zustellungen auf deinem Entwicklungsserver.

Einrichtung

Installiere ngrok:

bash

# macOS (Homebrew)
brew install ngrok

# Or download from https://ngrok.com/download

Starte deinen lokalen Webhook-Server (z. B. auf Port 3001):

bash

node server.js
# or
python app.py

Starte einen ngrok-Tunnel:

bash

ngrok http 3001

Kopiere die HTTPS-Weiterleitungs-URL aus der ngrok-Ausgabe:

text

Forwarding  https://a1b2c3d4.ngrok-free.app -> http://localhost:3001

Setze die ngrok-URL als deinen Webhook-Endpunkt:

bash

curl -X PUT https://app.nueform.com/api/v1/webhooks/form/YOUR_FORM_ID \
  -H "Authorization: Bearer nf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://a1b2c3d4.ngrok-free.app/webhooks/nueform" }'

Übermittle eine Antwort auf dein Formular. Der Webhook kommt bei deinem lokalen Server an.

Traffic inspizieren

ngrok bietet unter http://localhost:4040 eine lokale Weboberfläche, in der du alle Anfragen durch den Tunnel inspizieren, erneut senden und Header sowie Statuscodes einsehen kannst.

Kostenlose ngrok-URLs ändern sich bei jedem Neustart von ngrok. Denke daran, deine Webhook-URL in NueForm zu aktualisieren, wenn du eine neue Tunnel-URL erhältst. Für eine stabile Subdomain lohnt sich ein bezahlter ngrok-Tarif.

Option 3: curl (Payloads simulieren)

Mit curl kannst du Test-Payloads an deinen lokalen Server senden, ganz ohne NueForm. Das ist praktisch, um deine Verifizierungs- und Verarbeitungslogik isoliert zu testen.

Signierte Test-Payload erzeugen

Erstelle zuerst eine Test-Payload und signiere sie mit deinem Webhook-Secret:

bash

# Your webhook secret (from the NueForm API or dashboard)
SECRET="a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2"

# The test payload
PAYLOAD='{
  "event": "form.submitted",
  "formId": "507f1f77bcf86cd799439011",
  "formTitle": "Test Form",
  "responseId": "507f1f77bcf86cd799439022",
  "answers": [
    { "questionId": "507f1f77bcf86cd799439033", "value": "Test answer" },
    { "questionId": "507f1f77bcf86cd799439044", "value": 5 }
  ],
  "submittedAt": "2025-03-15T14:32:07.123Z"
}'

# Compute the HMAC-SHA256 signature
SIGNATURE=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')

echo "Signature: $SIGNATURE"

Signierte Anfrage senden

bash

curl -X POST http://localhost:3001/webhooks/nueform \
  -H "Content-Type: application/json" \
  -H "X-NueForm-Signature: $SIGNATURE" \
  -d "$PAYLOAD"

Einzeiler

Alles kombiniert in einem einzigen Befehl:

bash

SECRET="your_secret_here"
PAYLOAD='{"event":"form.submitted","formId":"507f1f77bcf86cd799439011","formTitle":"Test Form","responseId":"507f1f77bcf86cd799439022","answers":[{"questionId":"q1","value":"hello"}],"submittedAt":"2025-03-15T14:32:07.123Z"}'
SIGNATURE=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')

curl -X POST http://localhost:3001/webhooks/nueform \
  -H "Content-Type: application/json" \
  -H "X-NueForm-Signature: $SIGNATURE" \
  -d "$PAYLOAD"

Ablehnung ungültiger Signaturen testen

Um zu prüfen, ob dein Endpunkt ungültige Signaturen korrekt ablehnt, sende eine Anfrage mit falscher Signatur:

bash

curl -X POST http://localhost:3001/webhooks/nueform \
  -H "Content-Type: application/json" \
  -H "X-NueForm-Signature: 0000000000000000000000000000000000000000000000000000000000000000" \
  -d '{"event":"form.submitted","formId":"test","formTitle":"Test","responseId":"test","answers":[],"submittedAt":"2025-03-15T14:32:07.123Z"}'

Dein Endpunkt sollte 401 Unauthorized zurückgeben.

Option 4: Node.js-Testskript

Erstelle ein eigenständiges Node.js-Skript, um Test-Payloads schnell zu signieren und zu senden:

javascript

import crypto from 'crypto';

const SECRET = process.env.NUEFORM_WEBHOOK_SECRET || 'your_secret_here';
const ENDPOINT = process.env.WEBHOOK_URL || 'http://localhost:3001/webhooks/nueform';

const payload = JSON.stringify({
  event: 'form.submitted',
  formId: '507f1f77bcf86cd799439011',
  formTitle: 'Customer Feedback Survey',
  responseId: crypto.randomUUID().replace(/-/g, '').slice(0, 24),
  answers: [
    { questionId: 'q_name', value: 'Jane Doe' },
    { questionId: 'q_email', value: 'jane@example.com' },
    { questionId: 'q_rating', value: 4 },
    { questionId: 'q_feedback', value: 'Great product!' },
    { questionId: 'q_features', value: ['Feature A', 'Feature C'] },
  ],
  submittedAt: new Date().toISOString(),
});

const signature = crypto
  .createHmac('sha256', SECRET)
  .update(payload)
  .digest('hex');

const response = await fetch(ENDPOINT, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-NueForm-Signature': signature,
  },
  body: payload,
});

console.log(`Status: ${response.status}`);
console.log(`Body: ${await response.text()}`);

Starte es mit:

bash

NUEFORM_WEBHOOK_SECRET=your_secret node test-webhook.mjs

Option 5: Echte Übermittlung auslösen

Der gründlichste Test ist, eine echte Antwort auf dein Formular zu übermitteln:

Konfiguriere deine Webhook-URL (pro Formular oder global) auf deinen Test-Endpunkt.
Öffne dein veröffentlichtes Formular im Browser.
Fülle das Formular aus und schicke es ab.
Beobachte die Webhook-Zustellung auf deinem Endpunkt.

Damit testest du die gesamte Pipeline von Anfang bis Ende — inklusive Antwortvalidierung, Quiz-Auswertung und der tatsächlich von NueForm erzeugten Payload.

Fehlgeschlagene Zustellungen debuggen

Wenn dein Webhook-Endpunkt keine Anfragen erhält, arbeite diese Checkliste durch:

1. Prüfe, ob die URL konfiguriert ist

bash

# Check per-form webhook
curl https://app.nueform.com/api/v1/webhooks/form/YOUR_FORM_ID \
  -H "Authorization: Bearer nf_your_api_key"

# Check global webhooks
curl https://app.nueform.com/api/v1/webhooks/global \
  -H "Authorization: Bearer nf_your_api_key"

2. Prüfe, ob die URL erreichbar ist

bash

# Test that your endpoint accepts POST requests
curl -X POST https://your-endpoint.com/webhooks/nueform \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

3. Prüfe, ob ein Webhook-Secret existiert

Webhooks werden nur versendet, wenn für dein Konto ein Webhook-Secret gesetzt ist. Prüfe das so:

bash

curl https://app.nueform.com/api/v1/webhooks/secret \
  -H "Authorization: Bearer nf_your_api_key"

Zeigt die Antwort ein Secret, ist alles in Ordnung. Falls nicht, wird durch genau diese Anfrage automatisch eines erzeugt.

Fehler	Lösung
`express.json()`-Middleware vor der Signaturprüfung	Verwende `express.raw({ type: 'application/json' })` auf der Webhook-Route
Testen mit einem widerrufenen oder abgelaufenen API-Schlüssel	Erstelle einen frischen API-Schlüssel
Globale Webhooks nicht aktiviert	Setze `"enabled": true` bei jedem globalen Webhook-Eintrag
HTTP statt HTTPS für die Webhook-URL	NueForm sendet an jede angegebene URL, aber nutze in der Produktion HTTPS
Kein Webhook-Secret vorhanden	Stelle sicher, dass dein Konto ein Webhook-Secret hat, bevor du Zustellungen erwartest

Nächste Schritte

Überblick --- So funktionieren Webhooks in NueForm
Payloads --- Das Payload-Format verstehen
Verifizierung --- Signaturprüfung implementieren

Option 1: webhook.site (schnelle Inspektion)

Option 2: ngrok (lokale Entwicklung)

Einrichtung

Traffic inspizieren

Option 3: curl (Payloads simulieren)

Signierte Test-Payload erzeugen

Signierte Anfrage senden

Einzeiler

Ablehnung ungültiger Signaturen testen

Option 4: Node.js-Testskript

Option 5: Echte Übermittlung auslösen

Fehlgeschlagene Zustellungen debuggen

1. Prüfe, ob die URL konfiguriert ist

2. Prüfe, ob die URL erreichbar ist

3. Prüfe, ob ein Webhook-Secret existiert

4. Prüfe deinen Tarif

5. Prüfe das Timeout

6. Prüfe Firewall- und Netzwerkregeln

Häufige Fehler beim Testen

Nächste Schritte