Webhooks (JSON)

Eine Webhook-Regel sendet jede passende Antwort per POST als JSON an eine URL Ihrer Wahl. Nutzen Sie sie, um ein CRM, ein Tabellen-Tool, Ihren eigenen Server oder eine Automatisierungsplattform wie Zapier, Make oder n8n zu befüllen.

Eine Webhook-Regel erstellen

1. Klicken Sie auf + Neue Regel und wählen Sie Webhook
2. Wann: Behalten Sie Jede Antwort oder wählen Sie Erst nach Genehmigung / Bei Ablehnung und legen Sie eine genehmigende Person fest. Fügen Sie Bedingungen unter Nur falls hinzu, um nur passende Antworten zu senden
3. An: Fügen Sie die URL Ihres Endpunkts ein (nur HTTPS). Es gibt keinen Schritt Nachricht: Die Regel sendet eine feste JSON-Payload. Payload anzeigen unter der URL zeigt sie mit den Fragen Ihres Formulars, zum Kopieren bereit
4. Klicken Sie auf Regel erstellen und kopieren Sie dann das einmalig angezeigte Signaturgeheimnis (siehe unten)

Test senden schickt eine signierte Beispiel-Payload an den Endpunkt und zeigt den zurückgegebenen HTTP-Status. Gespeicherte URLs werden verschlüsselt abgelegt und maskiert angezeigt; klicken Sie auf Ersetzen, um eine neue einzufügen.

Die Payload

Jede Anfrage ist ein POST mit Content-Type: application/json und diesem Body:

{
  "version": 1,
  "event": "submitted",
  "form": { "id": "1AbC...", "name": "Workshop sign-up" },
  "response": {
    "id": "a3f1...",
    "submittedAt": "2026-01-31T09:30:00.000Z",
    "respondentEmail": "respondent@example.com",
    "answers": [
      { "questionId": "q1", "title": "Your name", "value": "Ada Lovelace" },
      { "questionId": "q3", "title": "Department", "value": "Ops" }
    ]
  },
  "rule": { "id": "rule id", "name": "Zapier: new lead" }
}

• event ist einer der Werte submitted, approved, rejected; er steht auch im Header X-Skyfield-Event
• response.respondentEmail ist null, sofern das Formular keine E-Mail-Adressen erfasst
• answers[].value ist immer ein String; Kästchen-Antworten werden mit , verbunden
• rule.id und rule.name identifizieren die Regel, die ausgelöst hat; name ist null, wenn die Regel keinen Namen hat
• Bei approved und rejected ist zusätzlich approval: { "decision": "approved", "decidedBy": "Dana" } enthalten. decidedBy ist der Name, den die genehmigende Person auf der Genehmigungsseite eingegeben hat, sonst die E-Mail-Adresse der genehmigenden Person, oder null

version bleibt 1, solange die obige Struktur stabil ist. Neue Felder können hinzukommen; ohne Versionssprung wird keines entfernt oder umbenannt.

Die Signatur prüfen

Jede Anfrage trägt einen Header X-Skyfield-Signature: sha256=<hex>, der HMAC-SHA256 des rohen Request-Bodys, mit dem Signaturgeheimnis Ihrer Regel als Schlüssel. Prüfen Sie ihn, bevor Sie einer Anfrage vertrauen.

Das Geheimnis (whsec_...) wird einmal angezeigt, direkt nach dem Speichern, das der Regel ihre erste Webhook-URL gibt. Kopieren Sie es dann; es kann nicht erneut angezeigt werden. Wird die URL später ersetzt, bleibt das Geheimnis gleich. Wenn Sie es verlieren, öffnen Sie die Regel, klicken Sie auf Neues Signaturgeheimnis und speichern Sie: Das neue Geheimnis wird einmal angezeigt, und das alte funktioniert sofort nicht mehr.

Berechnen Sie den HMAC über die Body-Bytes genau so, wie sie empfangen wurden. Wird das JSON zuerst geparst und neu serialisiert, ändern sich Leerzeichen und der Vergleich schlägt fehl.

Node.js

import { createHmac, timingSafeEqual } from 'node:crypto'

// rawBody: string or Buffer of the request body, before any JSON parsing
function verify(rawBody, header, secret) {
  const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex')
  const a = Buffer.from(expected)
  const b = Buffer.from(header ?? '')
  return a.length === b.length && timingSafeEqual(a, b)
}

// Express example: use express.raw() so req.body is the untouched bytes
app.post('/hook', express.raw({ type: 'application/json' }), (req, res) => {
  if (!verify(req.body, req.get('X-Skyfield-Signature'), process.env.SKYFIELD_SECRET))
    return res.status(401).end()
  const payload = JSON.parse(req.body)
  res.status(200).end()
})

Python

import hmac, hashlib

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    digest = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest("sha256=" + digest, header or "")

# Flask example
@app.post("/hook")
def hook():
    if not verify(request.get_data(), request.headers.get("X-Skyfield-Signature"), SECRET):
        return "", 401
    payload = request.get_json()
    return "", 200

Antworten Sie mit einem beliebigen 2xx-Status. Der Body wird ignoriert.

Zapier, Make, n8n

Alle drei akzeptieren einen generischen JSON-Webhook:

• Zapier: Trigger Webhooks by Zapier, Ereignis Catch Hook (oder Catch Raw Hook, um die Signatur selbst zu prüfen). Fügen Sie die von Zapier angezeigte URL in die Regel ein
• Make: Fügen Sie ein Webhooks-Modul hinzu, Custom webhook, und kopieren Sie dessen URL
• n8n: Fügen Sie einen Webhook-Node hinzu, Methode POST, und nutzen Sie dessen Produktions-URL

Senden Sie einen Test aus der Regel und ordnen Sie dann die Felder aus response.answers in der Plattform zu. Die Beispiel-Payload verwendet Platzhalter-Antworten, damit jedes Feld vorhanden ist.

Zustellung und Limits

• Der Endpunkt muss über das öffentliche Internet per HTTPS erreichbar sein. Private und lokale Adressen werden beim Speichern abgelehnt
• Weiterleitungen werden nicht gefolgt: Verwenden Sie die endgültige URL
• Der Endpunkt hat 5 Sekunden Zeit zu antworten. Ein Timeout oder eine 5xx-Antwort wird einmal wiederholt
• Eine 404- oder 410-Antwort bedeutet, dass der Endpunkt nicht mehr existiert: Die Regel wird pausiert und Sie erhalten einmalig eine E-Mail. Fügen Sie in der Regel eine neue URL ein, um fortzufahren
• Die Seite Verlauf listet jede Zustellung mit dem HTTP-Status, den Ihr Endpunkt zurückgegeben hat
• Eine pausierte oder ausgeschaltete Webhook-Regel blockiert keine anderen Regeln des Formulars

Gut zu wissen

• Eine Webhook-Regel beachtet Senden, wenn, sodass ein Endpunkt statt jeder Einsendung eine Genehmigungsentscheidung erhalten kann. Siehe Senden, wenn
• Um nur geprüfte Antworten zu senden, stellen Sie das Senden, wenn der Regel auf Erst nach Genehmigung und wählen Sie eine genehmigende Person. Siehe Genehmigung. Die Payload enthält dann approval.decision
• Kanal ändern… stellt eine Webhook-Regel auf E-Mail oder einen Chat-Kanal um; geben Sie dort das neue Ziel an. Beim Zurückwechseln zu Webhook muss die URL erneut eingefügt werden
• Webhook-Regeln brauchen eine aktive Lizenz. Die kostenlose Testphase zählt. Siehe was eine Lizenz benötigt