Webhook: Was ist das und wie verbindet man KI mit Formularen?

👁 112 Aufrufe

Ein Webhook ist eine URL-Adresse, an die eine Anwendung automatisch Daten an eine andere sendet, sobald ein bestimmtes Ereignis eintritt: jemand füllt ein Formular aus, eine E-Mail trifft ein oder eine Zahlung geht ein. Statt jede Minute nachzufragen, ob es Neuigkeiten gibt, warten Sie einfach ab, bis die Daten angeliefert werden. Im Folgenden zeige ich Webhooks in der Praxis: Ein lokaler Python-Server (FastAPI) empfängt Formulardaten, ein KI-Modell klassifiziert die Anfrage, erstellt einen Antwortentwurf und trägt das Ergebnis in eine Tabelle ein. Danach beschreibe ich dieselbe Lösung für Make und Zapier. Dieser Leitfaden ist Teil des Automatisierungsmoduls aus der Reihe KI-Agenten von Grund auf.

Webhook einfach erklärt

Es gibt zwei Wege, über die ein Programm von einem neuen Ereignis erfährt:

• Regelmässige Abfrage (Polling): Ihr Programm sieht alle 5 Minuten in einem Postfach oder einer Tabelle nach, ob neue Einträge vorhanden sind. Das ist einfach einzurichten, reagiert jedoch verzögert und verbraucht unnötig Abfragen.
• Webhook: Sie hinterlegen bei der externen Anwendung eine eigene Zieladresse (z. B. https://ihredomaene.de/webhook/formular). Diese sendet umgehend einen HTTP-POST-Request mit den Nutzdaten im JSON-Format, sobald etwas passiert.

Ein Webhook ist im Grunde ein gewöhnlicher API-Aufruf, nur in umgekehrter Richtung: Nicht Sie fragen einen Dienst an, sondern der Dienst ruft Ihr System auf. Falls HTTP-Anfragen und JSON neu für Sie sind, empfiehlt sich unser einführender Leitfaden zu APIs.

Typische Webhook-Quellen:

• Formulare (Tally, Typeform, Google Formulare via Skript, Formular-Plugins für WordPress);
• Zahlungsanbieter (Stripe, PayU benachrichtigen über Zahlungseingänge);
• Online-Shops (WooCommerce, Shopify übermitteln neue Bestellungen);
• Produktivitätswerkzeuge (GitHub, Slack, Trello, Calendly);
• Automatisierungsplattformen (Make, Zapier und n8n bieten fertige Webhook-Trigger).

Der Ablauf des Praxisbeispiels

1. Ein Kontaktformular überträgt JSON-Daten: Name, E-Mail-Adresse und Nachricht.
2. Der Server prüft das übermittelte Geheimnis im Request-Header, um unberechtigte Anfragen abzublocken.
3. Ein KI-Modell verarbeitet den Text und liefert ein JSON-Objekt zurück: Kategorie, Dringlichkeit von 1 bis 3, Zusammenfassung und ein Antwortentwurf.
4. Der Server hängt den Datensatz an eine CSV-Datei an (das lokale Äquivalent einer Tabellenkalkulation) und gibt das Ergebnis zurück.

Code des Webhook-Servers

Installation der benötigten Pakete: pip install fastapi uvicorn openai python-dotenv. In der Datei .env werden OPENROUTER_API_KEY sowie WEBHOOK_SECRET (eine lange Zufallszeichenfolge) hinterlegt.

"""06 - Webhook: Formular sendet Anfrage -> Server befragt KI-Modell -> Ergebnis landet in CSV-Tabelle und HTTP-Antwort.
Start:  uvicorn 06_webhook:app --port 8000      (oder: python 06_webhook.py)
Test:   curl -X POST http://127.0.0.1:8000/webhook/formular -H "X-Webhook-Secret: ..." -H "Content-Type: application/json"
             -d "{\"name\":\"Ola\",\"email\":\"ola@example.com\",\"nachricht\":\"Rechnung enthaelt falsche USt-IdNr.\"}"
"""
import csv, datetime, json, os, pathlib
from dotenv import load_dotenv
from fastapi import FastAPI, Header, HTTPException
from openai import OpenAI
from pydantic import BaseModel

load_dotenv()
SEKRET = os.getenv("WEBHOOK_SECRET", "bitte-aendern")    # dieselbe Zeichenkette wird in Make/Zapier/Formular hinterlegt
MODEL = os.getenv("MODEL", "openai/gpt-5.6-luna")
TABELLE = pathlib.Path("anfragen.csv")
client = OpenAI(base_url="https://openrouter.ai/api/v1", api_key=os.environ["OPENROUTER_API_KEY"])
app = FastAPI()

class Anfrage(BaseModel):             # Struktur der vom Formular uebermittelten JSON-Daten
    name: str
    email: str
    nachricht: str

@app.post("/webhook/formular")
def empfangen(a: Anfrage, x_webhook_secret: str = Header(default="")):
    if x_webhook_secret != SEKRET:    # Ohne diesen Check koennte jeder die URL aufrufen und Tokens verbrauchen
        raise HTTPException(status_code=401, detail="Ungueltiges Token")
    # Deutsche Uebersetzung des im urspruenglichen Test auf Polnisch ausgefuehrten System-Prompts:
    r = client.chat.completions.create(model=MODEL, response_format={"type": "json_object"}, messages=[
        {"role": "system", "content": "Du bist Support-Assistent. Liefere ein JSON mit den Feldern: kategorie (rechnungen|"
         "reklamation|angebot|sonstiges), dringlichkeit (1-3, 3 = dringend), zusammenfassung (max 12 Woerter), entwurf_antwort (2-3 Saetze, persoenlich)."},
        {"role": "user", "content": f"Von: {a.name}\nNachricht: {a.nachricht}"}])
    ergebnis = json.loads(r.choices[0].message.content)
    neu = not TABELLE.exists()
    with TABELLE.open("a", newline="", encoding="utf-8-sig") as f:  # utf-8-sig sorgt fuer korrekte Darstellung in Excel
        w = csv.writer(f, delimiter=";")
        if neu: w.writerow(["zeit", "name", "email", "kategorie", "dringlichkeit", "zusammenfassung", "entwurf_antwort"])
        w.writerow([datetime.datetime.now().isoformat(timespec="seconds"), a.name, a.email, ergebnis.get("kategorie"),
                    ergebnis.get("dringlichkeit"), ergebnis.get("zusammenfassung"), ergebnis.get("entwurf_antwort")])
    return {"ok": True, **ergebnis, "kosten_usd": getattr(r.usage, "cost", None)}

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="127.0.0.1", port=8000)

Zentrale Bestandteile der Implementierung:

• class Anfrage(BaseModel) definiert die JSON-Struktur. FastAPI verwirft Anfragen ohne Pflichtfelder vollautomatisch mit dem HTTP-Status 422, noch bevor Kosten für ein KI-Modell entstehen;
• Das Geheimnis im Header X-Webhook-Secret: Errät jemand die URL, wird der Zugriff mit 401 verweigert;
• response_format={"type": "json_object"} veranlasst das Modell, sauberes JSON auszugeben;
• utf-8-sig gewährleistet beim CSV-Export die fehlerfreie Anzeige von Umlauten und Sonderzeichen in Microsoft Excel.

Ausführung und Testlauf

Im ersten Terminalfenster starten wir den Server: uvicorn 06_webhook:app --port 8000. Im zweiten Terminal führen wir ein Testskript aus, das drei Anfragen sowie einen Aufruf mit fehlerhaftem Autorisierungstoken simuliert. Hinweis: Die Eingaben wurden ursprünglich auf Polnisch getestet; hier sind sie zur Veranschaulichung ins Deutsche übersetzt dargestellt:

"""Sendet 3 Beispielanfragen an den lokalen Webhook (wie ein Formular oder Make/Zapier)."""
import os, time, requests
URL = "http://127.0.0.1:8000/webhook/formular"
SEKRET = os.getenv("WEBHOOK_SECRET", "bitte-aendern")
print("Falsches Secret ->", requests.post(URL, json={"name": "X", "email": "x@example.com", "nachricht": "test"},
                                         headers={"X-Webhook-Secret": "geraten"}).status_code)
# Uebersetzung der urspruenglich auf Polnisch getesteten Eingaben:
for name, text in [("Ola", "Guten Tag, auf der Rechnung FV/2026/09/027 ist die USt-IdNr. meiner Firma falsch. Ich benoetige die Korrektur bis Freitag fuer den Monatsabschluss."),
                   ("Marek", "Was kostet die Implementierung eines Chatbots fuer einen Online-Shop mit 300 Produkten? Mich interessiert ein Termin im November."),
                   ("Kasia", "Das gelieferte Kabel ist beschaedigt angekommen, der Stecker ist gebrochen. Ich moechte eine Rueckerstattung.")]:
    t = time.time()
    r = requests.post(URL, json={"name": name, "email": f"{name.lower()}@example.com", "nachricht": text},
                      headers={"X-Webhook-Secret": SEKRET}, timeout=60)
    print(f"\n{name}: {text}\n-> HTTP {r.status_code} in {time.time() - t:.1f} s: {r.json()}")

Testergebnis vom 4. Oktober (Originaltest auf Polnisch durchgeführt, hier übersetzt dargestellt):

> python 06_test_webhook.py
Falsches Secret -> 401

Ola: Guten Tag, auf der Rechnung FV/2026/09/027 ist die USt-IdNr. meiner Firma falsch. Ich benoetige die Korrektur bis Freitag fuer den Monatsabschluss.
-> HTTP 200 in 2.1 s: {'ok': True, 'kategorie': 'rechnungen', 'dringlichkeit': 3, 'zusammenfassung': 'Falsche USt-IdNr. auf Rechnung, Korrektur bis Freitag noetig', 'entwurf_antwort': 'Vielen Dank fuer die Nachricht - wir pruefen die Rechnung FV/2026/09/027 und erstellen eine Korrektur. Wir kuemmern uns dringend darum, damit alles bis Freitag vorliegt.', 'kosten_usd': 0.0001746}

Marek: Was kostet die Implementierung eines Chatbots fuer einen Online-Shop mit 300 Produkten? Mich interessiert ein Termin im November.
-> HTTP 200 in 1.8 s: {'ok': True, 'kategorie': 'angebot', 'dringlichkeit': 2, 'zusammenfassung': 'Anfrage zu Kosten und Termin fuer Shop-Chatbot', 'entwurf_antwort': 'Hallo Marek, wir erstellen gerne ein Angebot fuer den Shop mit 300 Produkten und pruefen Termine im November. Bitte sende uns die Shop-URL und gewuenschte Funktionen.', 'kosten_usd': 0.000162}

Kasia: Das gelieferte Kabel ist beschaedigt angekommen, der Stecker ist gebrochen. Ich moechte eine Rueckerstattung.
-> HTTP 200 in 1.7 s: {'ok': True, 'kategorie': 'reklamation', 'dringlichkeit': 2, 'zusammenfassung': 'Beschaedigtes Kabel, Stecker defekt; Kundin wuenscht Erstattung.', 'entwurf_antwort': 'Es tut uns leid, dass das Kabel beschaedigt ankam. Bitte sende uns Fotos des Schadens und die Bestellnummer, damit wir die Erstattung veranlassen koennen.', 'kosten_usd': 0.0001504}

> type anfragen.csv
zeit;name;email;kategorie;dringlichkeit;zusammenfassung;entwurf_antwort
2026-10-04T14:11:16;Ola;ola@example.com;rechnungen;3;Falsche USt-IdNr. auf Rechnung, Korrektur bis Freitag noetig;Vielen Dank fuer die Nachricht - wir pruefen die Rechnung FV/2026/09/027 und erstellen eine Korrektur. Wir kuemmern uns dringend darum, damit alles bis Freitag vorliegt.
2026-10-04T14:11:18;Marek;marek@example.com;angebot;2;Anfrage zu Kosten und Termin fuer Shop-Chatbot;Hallo Marek, wir erstellen gerne ein Angebot fuer den Shop mit 300 Produkten und pruefen Termine im November. Bitte sende uns die Shop-URL und gewuenschte Funktionen.
2026-10-04T14:11:19;Kasia;kasia@example.com;reklamation;2;"Beschaedigtes Kabel, Stecker defekt; Kundin wuenscht Erstattung.";Es tut uns leid, dass das Kabel beschaedigt ankam. Bitte sende uns Fotos des Schadens und die Bestellnummer, damit wir die Erstattung veranlassen koennen.

Erkenntnisse aus dem Testlauf:

• Anfragen mit ungültigem Token wurden unmittelbar mit Status 401 abgewiesen, ohne das KI-Modell aufzurufen.
• Die Zuordnung zu den Kategorien erfolgte in allen Fällen präzise. Dringlichkeitsstufe 3 wurde ausschliesslich bei der Fristangabe („bis Freitag“) vergeben, alle übrigen Fälle erhielten Stufe 2.
• Die generierten Rückmeldungen passten zum Kontext; im Reklamationsfall forderte das System selbständig Belegfotos und die Bestellnummer an.

Praxishinweis zu Windows: Wird curl in Git Bash unter Windows mit Umlauten direkt im Parameter -d '...' ausgeführt, kann eine fehlerhafte Zeichencodierung zu Status 400 führen („There was an error parsing the body“). Abhilfe schafft das Auslagern der Nutzlast in eine JSON-Datei mit dem Parameter --data-binary @datei.json oder der Einsatz des Python-Testskripts.

Den Webhook öffentlich verfügbar machen

Ein Dienst unter 127.0.0.1 ist nur lokal erreichbar. Damit Formulare aus dem Internet Daten anliefern können, wird eine öffentliche Adresse benötigt:

• Für Testzwecke: Tunneldienste wie ngrok oder Cloudflare Tunnel erstellen eine temporäre HTTPS-URL, die eingehende Anfragen an den lokalen Port 8000 weiterleitet.
• Für den Dauerbetrieb: Ein Cloud-Hosting oder ein kleiner Server, beispielsweise über Railway.
• Ohne eigene Serverinfrastruktur: Der Empfang erfolgt ueber Make, Zapier oder n8n, von wo aus die Modellabfrage angestossen wird.

Verwenden Sie im Produktivbetrieb stets HTTPS und ein Autorisierungsgeheimnis. Etablierte Plattformen (wie Stripe oder GitHub) signieren Anfragen zusätzlich via HMAC. In diesem Fall prüft der Server nicht nur einen statischen Header, sondern verifiziert die Signatur über den Nachrichteninhalt.

Umsetzung in Make (No-Code)

1. Erstellen Sie ein neues Szenario und fügen Sie als ersten Baustein das Modul Webhooks, Custom webhook hinzu. Make stellt daraufhin eine URL-Adresse bereit.
2. Tragen Sie diese Adresse in den Einstellungen des Formulars ein (z. B. Tally, Typeform, WordPress) und senden Sie einen Testdatensatz ab, damit Make die JSON-Struktur erfasst.
3. Ergänzen Sie ein KI-Modul: OpenAI (oder ein HTTP-Modul für OpenRouter) mit strukturierter JSON-Ausgabe.
4. Fügen Sie das Modul JSON, Parse JSON ein, um die Datenfelder zu trennen.
5. Erstellen Sie ein Modul Google Sheets, Add a row und verknüpfen Sie die Datenfelder mit den Spalten.
6. Optional: Ein nachgeschalteter Filter für Datensätze mit hoher Dringlichkeit („dringlichkeit = 3“), der Benachrichtigungen auslöst.

Jede Ausführung verbraucht in Make einzelne Operations (eine pro Modul). Der kostenlose Tarif umfasst 1.000 Credits monatlich bei 2 aktiven Szenarien. Detaillierte Einblicke bietet der Beitrag Make: Funktionsweise und Kostenstruktur.

Umsetzung in Zapier

1. Trigger einrichten: Webhooks by Zapier, Catch Hook (erzeugt die Ziel-URL für das Formular). Alternativ lässt sich ein direkter Formular-Trigger nutzen, sofern integriert.
2. Aktion hinzufügen: ChatGPT oder AI by Zapier mit Anweisungen zur Klassifizierung.
3. Aktion hinzufügen: Google Sheets, Create Spreadsheet Row.

Webhooks zählen bei Zapier zu den Premium-Funktionen. Voraussetzung ist ein kostenpflichtiger Tarif (Professional ab ca. 17,88 EUR bzw. 19,99 USD monatlich bei jährlicher Zahlungsweise, rund 26,82 EUR bzw. 29,99 USD bei monatlicher Abrechnung; Wechselkurs der EZB vom 12.10.2026: 1 EUR = 1,1181 USD). Ein ausführlicher Systemvergleich findet sich im Artikel Zapier: Funktionen und Kosten im Überblick.

Vergleich: Eigener Code, Make oder Zapier

Häufig gestellte Fragen (FAQ)

Was ist ein Webhook in einfachen Worten?

Eine Web-Adresse, an die eine externe Anwendung automatisch Informationen überträgt, sobald ein bestimmtes Ereignis eingetreten ist.

Worin liegt der Unterschied zwischen Webhook und API?

Eine reguläre API-Schnittstelle wird aktiv abgefragt, wenn Daten benötigt werden. Ein Webhook funktioniert wie eine Klingel: Das empfangende System wird benachrichtigt, sobald auf der Gegenseite etwas passiert. Technisch gesehen ist ein Webhook ein API-Aufruf, der an Ihr System gerichtet ist.

Sind Webhooks sicher?

Die Sicherheit hängt von den getroffenen Schutzmassnahmen ab. Die Basis bilden eine verschlüsselte HTTPS-Verbindung sowie ein Prüftoken im Header. Für erhöhte Sicherheitsanforderungen empfiehlt sich eine kryptografische HMAC-Signatur, Zeitstempelprüfungen gegen Replay-Angriffe sowie eine Begrenzung der übertragenen Datenmenge.

Wie lassen sich Webhooks ohne öffentlichen Server testen?

Anfragen können direkt lokal über ein Testskript an 127.0.0.1 gerichtet werden. Alternativ leitet ein Tunneldienst öffentliche Anfragen sicher auf die lokale Testumgebung weiter.

Was geschieht bei einem Serverausfall?

Das hängt vom sendenden Dienst ab. Grosse Plattformen wie Stripe oder GitHub wiederholen fehlgeschlagene Zustellversuche über festgelegte Zeiträume. Einfache Webformulare verwerfen Datensätze unter Umständen direkt. Webhook-Server sollten daher zügig antworten und rechenintensive Schritte bei hohem Datenaufkommen asynchron im Hintergrund verarbeiten.

Lässt sich ein Webhook mit KI-Agenten kombinieren?

Ja, Webhooks dienen haeufig als Ausloeser fuer Agentenarchitekturen: Das eingehende Ereignis stoesst statt eines einfachen Einzelaufrufs eine flexible Arbeitsschleife mit Zugriff auf Werkzeuge an. Eine genaue Anleitung dazu finden Sie im Beitrag KI-Agenten mit Python entwickeln.

Quellen und Prüfstand

• Preisangaben: Make, Zapier, n8n (abgerufen am 4. Oktober 2026). Währungsumrechnungen basieren auf dem Referenzkurs der Europäischen Zentralbank vom 12.10.2026 (1 EUR = 1,1181 USD; Quelle: EZB).
• FastAPI Dokumentation.
• Testdurchführung: Lokale Testumgebung, 4. Oktober 2026. Sämtliche Anfragedaten sind fiktiv.

// weiterlesenWie eine E-Mail auf Englisch schreiben mit KI: Schritt für SchrittAnleitungenWie einen LinkedIn-Post schreiben mit KI: Schritt für SchrittAnleitungenWie einen Lernplan erstellen mit KI: Schritt für SchrittAnleitungen

Kinetyra