Formular-Webhook: Antworten automatisch weiterverarbeiten

Ein Formular ist selten das Ende eines Prozesses. Die Anfrage soll ins CRM, das Team soll Bescheid wissen, ein eigener Dienst soll weiterrechnen. Ein Formular-Webhook erledigt diese Übergabe automatisch – ohne Export, ohne Abtippen. Dieser Artikel erklärt, was ein Webhook ist, wie das Event von Formenio aufgebaut ist, wie du den Empfang absicherst und wie du dich gegen verlorene Aufrufe wappnest.

Was ein Webhook ist – und worin er sich von einer API unterscheidet

Ein Webhook ist ein HTTP-Aufruf, den ein System von sich aus an eine Adresse schickt, sobald etwas passiert. Diese Adresse heißt Endpunkt: eine URL, hinter der ein Programm auf eingehende Daten wartet.

Der Unterschied zu einer klassischen API liegt in der Richtung. Bei einer API fragt dein System regelmäßig nach: „Gibt es neue Antworten?“ Das nennt man Polling, und meistens lautet die Antwort „nein“. Beim Webhook dreht sich das um: Formenio meldet sich, wenn eine Antwort eingeht, und liefert die Daten gleich mit. Das ist schneller, spart unnötige Anfragen und hält beide Seiten einfach.

Der Preis dafür: Dein Endpunkt muss erreichbar sein, wenn der Aufruf kommt, und er muss damit umgehen können, dass jeder im Internet die URL theoretisch ansprechen kann. Um beides geht es weiter unten.

Wann sich ein Formular-Webhook lohnt

Nicht jede Weiterverarbeitung braucht einen Webhook. Für viele Ziele gibt es in Formenio einen kürzeren Weg:

Wenn das Ziel eine Tabelle ist, zeigt Formular mit Google Sheets verbinden den Weg ohne Code. Der Webhook spielt seine Stärke dort aus, wo es keine fertige Integration gibt oder wo du die Daten in einem eigenen System brauchst.

Eine Einschränkung betrifft Chat-Tools: Dienste wie Slack erwarten bei ihren eingehenden Webhooks ein eigenes Nachrichtenformat. Das Formenio-Event lässt sich deshalb nicht direkt dorthin schicken, sondern braucht eine Zwischenstation, die die Daten in eine Nachricht übersetzt – einen kleinen eigenen Dienst oder eine Automatisierungsplattform.

Event-Webhook in Formenio einrichten

Webhooks laufen in Formenio über Workflows. Ein Workflow besteht aus einem Trigger und einer oder mehreren Aktionen.

1. Formular öffnen und in der Seitenleiste „Workflows“ wählen, dann „Neuer Workflow“.
2. Trigger festlegen: Name vergeben, Workflow aktivieren und zwischen „Bei Absenden“ und „Bei Absenden mit Bedingung“ wählen. Mit Bedingung löst nur aus, was etwa ein bestimmtes Feld befüllt hat oder einen bestimmten Text enthält.
3. Aktion „Event Webhook“ hinzufügen und die URL deines Endpunkts eintragen.
4. Workflow speichern. Danach wird dir die Workflow-ID angezeigt. Die brauchst du gleich für die Absicherung.

Aktionen werden der Reihe nach ausgeführt. Ein Workflow kann also zuerst eine Bestätigungsmail verschicken und danach den Webhook auslösen.

So sieht der Payload aus

Der Payload ist der Inhalt, den Formenio an deinen Endpunkt schickt. Aktuell gibt es ein Event: form.submitted, ausgelöst durch die abgeschickte Antwort. Die Formenio-Dokumentation zum Event Webhook zeigt dieses Beispiel:

{
  "event": "form.submitted",
  "formId": "69f1f9359b009a4048d629e4",
  "responseId": "2ed39c31-a9f9-4c34-9120-3a35f3a09415",
  "fields": {
    "harswmkul": {
      "label": "Textfeld Beispiel",
      "type": "text",
      "value": "Eingabetext"
    },
    "rn1juqvwg": {
      "label": "Kartenauswahl",
      "type": "cardSelect",
      "value": "Option 2"
    },
    "c7o9wpmuk": {
      "label": "Dateifeld Beispiel",
      "type": "file",
      "value": ["testfile2.txt"]
    }
  },
  "status": null,
  "submittedAt": "2026-04-29T12:30:09.268Z",
  "timestamp": "2026-04-29T12:30:09.273Z"
}

Die wichtigsten Teile:

• event sagt, was passiert ist. Prüfe den Wert, bevor du weiterverarbeitest – weitere Events sind laut Dokumentation geplant.
• formId und responseId identifizieren Formular und Antwort. Die responseId ist dein bester Schlüssel gegen Dubletten.
• fields enthält jedes Feld unter seiner Feld-ID mit Beschriftung (label), Typ (type) und Wert (value). Beim Dateifeld steht im Beispiel eine Liste von Dateinamen.
• status ist der Status der Antwort. Er bleibt null, solange ihn keine Workflow-Aktion „Status setzen“ verändert hat.
• submittedAt ist der Zeitpunkt des Absendens, timestamp gehört zum Event selbst.

Den Empfang absichern

Ein Endpunkt ist eine öffentliche URL. Ohne Prüfung könnte jeder, der sie kennt, Daten einschleusen. Formenio sendet deshalb bei jedem Aufruf einen Header mit: formenio, mit der Workflow-ID als Wert. Daraus ergeben sich ein paar Regeln:

• Header prüfen. Stimmt der Wert nicht mit deiner gespeicherten Workflow-ID überein, antwortet der Endpunkt mit 401 und verarbeitet nichts.
• Die Workflow-ID wie ein Passwort behandeln. Der Header ist ein gemeinsames Geheimnis, keine kryptografische Signatur über den Inhalt. Lege die ID als Umgebungsvariable ab, nicht im Frontend-Code oder in einem öffentlichen Repository, und schreibe sie nicht ins Log.
• Nur HTTPS verwenden, damit Header und Antwortdaten verschlüsselt übertragen werden.
• Inhalt plausibilisieren. Erwartet dein Endpunkt Daten aus genau einem Formular, prüfe zusätzlich die formId.

Ein schlanker Empfänger in Node.js mit Express könnte so aussehen:

import express from "express";
 
const app = express();
app.use(express.json());
 
const WORKFLOW_ID = process.env.FORMENIO_WORKFLOW_ID;
const verarbeitet = new Set(); // in der Praxis: Datenbank mit eindeutigem Index
const warteschlange = [];
 
app.post("/webhooks/formenio", (req, res) => {
  if (req.get("formenio") !== WORKFLOW_ID) {
    return res.sendStatus(401);
  }
 
  const { event, responseId, fields } = req.body;
  if (event !== "form.submitted") {
    return res.sendStatus(204);
  }
 
  if (!verarbeitet.has(responseId)) {
    verarbeitet.add(responseId);
    warteschlange.push({ responseId, fields }); // eigentliche Arbeit später
  }
 
  res.sendStatus(204);
});
 
app.listen(3000);

Das Beispiel ist bewusst knapp. Für den produktiven Einsatz gehören ein zeitkonstanter Vergleich des Headers, eine persistente Speicherung der verarbeiteten IDs und eine echte Warteschlange dazu.

Fehlerbehandlung und Retries: plane für den Ausfall

Retries sind automatische Wiederholungsversuche, wenn ein Aufruf fehlschlägt. Die Formenio-Dokumentation macht zu Wiederholungen, Timeouts und erwarteten Antwortcodes keine Angaben. Baue deinen Empfänger deshalb so, dass er nicht auf eine zweite Chance angewiesen ist:

Schnell quittieren, später arbeiten. Der Endpunkt nimmt die Daten an, prüft den Header, legt die Antwort ab und antwortet sofort mit einem 2xx-Code. Das CRM-Update oder die Chat-Nachricht passieren danach aus der Warteschlange heraus. So hängt die Übergabe nicht davon ab, ob das Zielsystem gerade langsam ist.

Idempotent verarbeiten. Idempotent heißt: Kommt dieselbe Antwort zweimal an, entsteht trotzdem nur ein Datensatz. Die responseId als eindeutiger Schlüssel sorgt dafür – egal, ob die Dublette aus einer Wiederholung, einem manuellen Nachspielen oder einem Fehler auf deiner Seite stammt.

Fehler im eigenen System selbst wiederholen. Scheitert die Weitergabe ans CRM, bleibt der Eintrag in der Warteschlange und wird mit wachsendem Abstand erneut versucht. Nach mehreren Fehlschlägen landet er in einer Fehlerliste, die jemand sichtet.

Abgleichen statt hoffen. Die vollständigen Antworten bleiben in Formenio. Vergleiche in regelmäßigen Abständen, ob alle responseIds angekommen sind, und hole Lücken über den Export nach.

Erst testen, dann anbinden. Richte den Webhook zunächst auf einen Testempfänger, der eingehende Anfragen samt Methode und Headern anzeigt. So siehst du genau, was ankommt, bevor dein Produktivsystem davon abhängt.

Unbekannte Felder tolerieren. Kommt im Formular ein Feld hinzu, taucht es im Payload auf. Dein Empfänger sollte zusätzliche Felder ignorieren können, statt mit einem Fehler abzubrechen.

Datenschutz: der Webhook ist eine Datenübermittlung

Mit jedem Aufruf verlassen personenbezogene Daten Formenio und landen in einem weiteren System. Prüfe deshalb, wo dein Endpunkt und das Zielsystem betrieben werden, ob mit diesen Anbietern ein Vertrag zur Auftragsverarbeitung besteht und ob wirklich alle Felder dort gebraucht werden. Über einen bedingten Trigger oder eine schlanke Feldauswahl im Empfänger hältst du die Kopie klein. Die Grundlagen zu Rechtsgrundlage, Löschfristen und Auftragsverarbeitung ordnet DSGVO-konforme Online-Formulare ein. Eine Rechtsberatung ersetzt das nicht.

Checkliste für deinen Formular-Webhook

• Ziel geprüft: Gibt es eine fertige Integration, die den Webhook überflüssig macht?
• Endpunkt per HTTPS erreichbar, zuerst mit Testempfänger ausprobiert
• Header formenio gegen die Workflow-ID geprüft, ID sicher abgelegt
• Zuordnung über Feld-IDs statt Labels
• responseId als eindeutiger Schlüssel gegen Dubletten
• Sofortige Quittung, Verarbeitung über eine Warteschlange
• Regelmäßiger Abgleich mit den Antworten in Formenio
• Datenfluss im Verzeichnis der Verarbeitungstätigkeiten ergänzt

Fazit

Ein Formular-Webhook macht aus einer eingegangenen Antwort einen automatischen nächsten Schritt in deinem System. In Formenio ist die Einrichtung schnell erledigt: Workflow anlegen, Aktion „Event Webhook“ wählen, URL eintragen. Die eigentliche Arbeit liegt auf der Empfängerseite – Header prüfen, sofort quittieren, idempotent verarbeiten und regelmäßig abgleichen. Wer das sauber aufsetzt, hat eine Übergabe, die auch dann trägt, wenn ein Zielsystem einmal ausfällt. Einen Überblick über Workflows, Bedingungen und Datensätze gibt die Funktionsübersicht, passende Formulare als Startpunkt findest du in den Vorlagen.