Webhooks

Mit dem Webhook-Zustelldienst können Sie Ihre Formularsendungen an externe Systeme senden, indem Sie Webhooks für Ihr Formular auf Form.taxi einrichten.

Was sind Webhooks?

Webhooks bieten eine einfache Möglichkeit, Ereignisse in Echtzeit an externe Dienste zu übertragen. Statt dass ein System regelmäßig abgefragt werden muss, sendet es bei einem definierten Ereignis - bei Form.taxi einer neuen Formularsendung - automatisch eine HTTP-Anfrage an eine zuvor festgelegte URL. Dadurch können andere Anwendungen sofort auf neue Daten reagieren, Prozesse anstoßen oder Informationen weiterverarbeiten. Webhooks sind damit ein leichtgewichtiges, effizientes Verfahren für die Integration zwischen verschiedenen Systemen.

Einrichtung

Mithilfe der Webhook-Funktion können Sie Formularsendungen an andere Apps und Dienste weiterleiten. Um Webhooks in Form.taxi zu verwenden, müssen Sie lediglich die Webhook-URL Ihres Formulars einrichten.

Nach erfolgreicher Einrichtung werden alle neuen Formularsendungen automatisch an die von Ihnen angegebene Webhook-URL gesendet, sobald diese eingehen.

1. Öffnen der Zustelleinstellungen des Formulars. Liste Ihre Formulare

2. Die Zustellfunktion Webhook aktivieren.

3. In den Webhook-Einstellungen Ihre URL eintragen.

Die Webhook-Funktion Ihres Formulars ist vollständig eingerichtet und bereit, Formulardaten an die gespeicherte URL zu senden.

Sendedaten

Bei der Ausführung des Webhooks werden die Sendungsdaten als POST-Request im JSON-Format an die eingetragenen Webadresse (URL) gesendet.

Beispiel der JSON-Struktur

{
  "submission_id": "EJg90qoBWzkxh0hYuoTQ3fHyTWFv4mCF",
  "submitted_at": "2025-11-27T11:51:26+01:00",
  "inputs": {
    "My Name": "Emma Pollarde",
    "Email": "demo@mailinator.com",
    "Your Message": "How are you doing?"
  },
  "attachments": [
    {
      "fieldName": "Bild",
      "fileName": "filename.jpg",
      "fileSize": 810097,
      "url": "https://form.taxi/download/GVsOkzZxF4JBpoPD/filename.jpg"
    },
    {
      "fieldName": "Dokument",
      "fileName": "filename.pdf",
      "fileSize": 1086378,
      "url": "https://form.taxi/download/2xTvyrtTAmMeC3sN/filename.pdf"
    }
  ]
}

Das Objekt inputs enthält die vom Formular übermittelten Formularfelder mit deren Namen und Eingabe. Beachten Sie, dass der Inhalt hier dynamisch ist, abhängig von den im Formular vorhandenen Eingabefeldern. Wenn mit der Formularsendung Dateianhänge mitgesendet wurden, sind diese im Array attachments abgebildet.

Request-Headers

Content-Type 	        application/json
User-Agent 	            FormTaxi-Webhook/1.0
Idempotency-Key 	    d477e8e263365a9252eba5aue427ceb2
X-FormTaxi-Timestamp 	1763823601
X-FormTaxi-Token 	    whtk_oSde7NGktXkPVPnd2ryQ7qr0yTf54iaz
X-FormTaxi-Signature    v1=3244f570aabd42c155fa72c522538a5185dfba8e62c56e8b9e8aebabe41c8a82

• Der Idempotency-Key-Header beinhaltet einen zufälligen Code, der für jeden Request anders ist. Damit kann im Zielsystem, durch einen Abgleich dieses Codes, die mehrfache Verarbeitung des Requests verhindert werden.
• X-FormTaxi-Timestamp Dieser UNIX-Timestamp gibt an, zu welchem Zeitpunkt der Request erstellt wurde.
• Der Token- und Signature-Header dienen zur Authentifizierung. Die Beschreibung dazu im folgenden Abschnitt.

Authentifizierung

Webhook-Endpunkte sollten nur Anfragen verarbeiten, die tatsächlich vom vorgesehenen Dienst stammen. Um sicherzustellen, dass eingehende Webhook-Requests vertrauenswürdig sind und nicht von Dritten manipuliert oder missbraucht werden, bietet Form.taxi zwei Authentifizierungsmechanismen an. Diese ermöglichen es dem Empfänger, die Herkunft und Integrität der Daten zu prüfen und damit die Sicherheit der Kommunikation zu gewährleisten.

Statischer Token

Ein Static Token ist die einfachste Form der Webhook-Authentifizierung. Dabei wird ein geheimer Token erzeugt, der nur dem Webhook-Empfänger und Form.taxi bekannt ist. Bei jedem Webhook-Request übermittelt Form.taxi diesen Token im Header:

X-FormTaxi-Token: <token>

Der Empfänger prüft lediglich, ob der übermittelte Token mit dem erwarteten Wert übereinstimmt. Ist dies der Fall, gilt der Request als authentisch. Sie finden Ihren Token in den Webhook-Einstellungen.

Signatur (HMAC-Signature)

Wenn Sie Ihre Webhooks besonders sicher gestalten möchten, können Sie die Signaturprüfung nutzen. Form.taxi signiert jeden Webhook-Request kryptografisch, sodass Sie zuverlässig prüfen können, ob der Request tatsächlich von Form.taxi stammt und ob der Inhalt unverändert übermittelt wurde.

Dafür sendet Form.taxi zwei Header mit:

X-FormTaxi-Timestamp: <unix timestamp>
X-FormTaxi-Signature: v1=<hex digest>

Wie wird die Signatur berechnet?

Zur Berechnung der Signatur werden zwei Werte kombiniert:

1. der Unix-Timestamp (als Header übermittelt)
2. den unveränderten JSON-Body des Requests (raw body)

Diese beiden Werte werden zu folgendem String zusammengeführt:

<timestamp>.<raw_body>

Dieser String wird anschließend mit Ihrem Webhook-Secret über HMAC-SHA256 signiert. Sie finden den Secret-Schlüssel in den Webhook-Einstellungen. Das Ergebnis ist ein Hex-Digest, der im Header X-FormTaxi-Signature übertragen wird.

Um den Request zu prüfen, berechnen Sie auf Ihrer Seite dieselbe Signatur und vergleichen den Wert mit dem übertragenen Header. Wenn beide Werte übereinstimmen - und der Timestamp innerhalb eines gültigen Zeitfensters liegt - können Sie sicher sein, dass der Request authentisch ist und nicht manipuliert wurde.

Ablaufsteuerung

Die Webhook-Ausführung wird seitens Form.taxi als erfolgreich erkannt, wenn Ihre Anwendung einen Erfolgs-Status (HTTP-Code 2xx) zurückliefert.

Wenn wir keinen Erfolgsstatus erhalten, versucht Form.taxi alle 15 Minuten den Request erneut zu senden, bis die erfolgreiche Ausführung registriert wird. Die Request-Versuche werden für max. 24 Stunden nach der Formularübermittlung ausgeführt.