Docs

Flow-Webhooks

Ereignis flow.webhook, Ausführungs-Snapshot, Signatur, Größenlimit und unabhängige Zustellung.

Ein Webhook-Schritt erzeugt flow.webhook, sobald er in einer veröffentlichten Sequenz erreicht wird. Er erfordert Pro und die Workspace-Freigabe. Das ist kein globales Ereignis-Abonnement: Ziele verwenden deliveryMode: "sequence" mit festem events: ["flow.webhook"]. Der Standardmodus events behält die neun auswählbaren Workspace-Ereignisse; flow.webhook lässt sich dort nicht ergänzen.

Payload und Identität

Calberry speichert beim Ausführen des Schritts einen festen JSON-Snapshot mit data.actor="system" und data.schema_version=1. created_at ist dieser Ausführungszeitpunkt, weder die Buchungserstellung noch der letzte Zustellversuch. Es gibt keine frei gestaltbare Request-Body-Vorlage und kein Mapping von Antwortvariablen.

Die normale öffentliche Hülle und die Schreibweise der Lead-/Booking-Felder gelten auch hier. Zusätzlich enthalten Flow-Ereignisse:

FeldBedeutung
data.flow.sequence_idIdentität der Sequenz über Versionen hinweg.
data.flow.version_idVeröffentlichte Sequenzversion dieses Laufs.
data.flow.node_idWebhook-Knoten im Graphen dieser Version.
data.flow.run_idSequenzlauf für diesen Termin.
data.flow.step_idDiese Schrittausführung; bei Retry und Replay unverändert.
data.hostHost-ID und Anzeigename, ohne Host-E-Mail oder Anbieterdaten.
data.funnelID und Name des Buchungslinks.

data.lead, data.booking, data.answers, data.attribution, data.form_version und die boolesche Nachfass-Einwilligung data.consent stammen aus dem Ausführungskontext. Sie belegen keinen neuen Formularabschluss und keine neue Einwilligung. lead.captured behält seine bisherige Bedeutung; ein Ereignis lead.submitted gibt es nicht.

Beispiel

Das ist ein vollständiges illustratives Flow-Ereignis mit erfundenen Kennungen und Kontaktdaten. Optionale Kontaktfelder und Zeitstempel können fehlen; Telefon und Teamreferenz können null sein. Synthetische Zustellungen über Test senden tragen zusätzlich data.test=true und Beispiel-Flow-IDs; schließe sie von Geschäftsaktionen aus.

{
  "event_id": "ev_example_flow",
  "type": "flow.webhook",
  "created_at": "2026-11-06T10:00:00.000Z",
  "data": {
    "actor": "system",
    "schema_version": 1,
    "workspace_id": "ws_example",
    "form_version": 1,
    "consent": false,
    "flow": {
      "sequence_id": "sq_example",
      "version_id": "sv_example",
      "node_id": "webhook",
      "run_id": "run_example",
      "step_id": "step_example"
    },
    "lead": {
      "id": "ld_example",
      "workspaceId": "ws_example",
      "funnelId": "fn_example",
      "name": "Alex Example",
      "email": "alex@example.invalid",
      "phone": null,
      "status": "booked",
      "createdAt": "2026-11-06T09:00:00.000Z"
    },
    "booking": {
      "id": "bk_example",
      "workspaceId": "ws_example",
      "funnelId": "fn_example",
      "hostId": "hs_example",
      "teamId": null,
      "leadId": "ld_example",
      "start": "2026-11-10T09:00:00.000Z",
      "end": "2026-11-10T09:30:00.000Z",
      "timeZone": "Europe/Vienna",
      "inviteeTimeZone": "Europe/London",
      "status": "confirmed",
      "createdAt": "2026-11-06T09:00:00.000Z"
    },
    "host": {
      "id": "hs_example",
      "name": "Example host"
    },
    "funnel": {
      "id": "fn_example",
      "name": "Example meeting"
    },
    "answers": {
      "topic": "First consultation"
    },
    "attribution": {
      "utm_source": "newsletter"
    }
  }
}

Aktions-Tokens, Umbuchungs-/Absagelinks, Meeting-Links, Host-E-Mail und Anbieterdaten sind nicht enthalten. Kopien in deinen Werkzeugen können außerhalb der EU gespeichert werden.

Signatur und Duplikate

Das vorhandene Signaturprotokoll samt Node.js-Verifier gilt unverändert: Webhook-Signature: t=<Unix-seconds>,v1=<hex> signiert <t>.<raw request body> mit HMAC-SHA256. Verwende das vollständige ausgegebene Secret als UTF-8 einschließlich whsec_, ohne Base64-Dekodierung. Webhook-Id enthält die Ereignis-ID; dedupliziere anhand von event_id im signierten Body.

Retry und Replay behalten exakten Body, event_id und alle fünf Flow-IDs, erhalten aber einen frischen Signaturzeitstempel. Verschiedene Webhook-Schritte erzeugen auch am selben Ziel verschiedene Ereignis-IDs. Verwende event_id gegen doppelte Wirkungen und data.flow zur Zuordnung von Schritt und Lauf; allein die Buchungs-ID würde unterschiedliche Schrittereignisse fälschlich zusammenfassen.

Make Custom webhook und Zapier Catch Hook können Flow-Ereignisse direkt ohne Signaturprüfung empfangen. Sie prüfen Calberrys HMAC nicht automatisch. Halte Empfangs-URLs vertraulich; benötigst du die Prüfung, schalte einen prüfenden Empfänger vor das Werkzeug.

Größenlimit nur für Flow-Webhooks

Das Limit für den ausgehenden JSON-Body beträgt standardmäßig 262.144 Bytes (256 KiB) und ist durch den Betreiber konfigurierbar. Es gilt ausschließlich für Flow-Webhooks, einschließlich Flow-Tests und Replay. Workspaceweite Ereignis-Webhooks erhalten dadurch kein Größenlimit.

Ein zu großer Snapshot erscheint als Dead-Letter mit payload_too_large, ohne HTTP-Anfrage. Der Transport prüft das Limit vor DNS/HTTP beim Versand erneut. Retry oder Replay desselben zu großen Bodys verkleinert ihn nicht. Die Sequenz setzt spätere Schritte einschließlich Kunden-E-Mails trotzdem fort.

Retry, Replay und Reihenfolge

Snapshot und Schrittabschluss werden vor dem Hintergrundversand gemeinsam dauerhaft gespeichert. Kein Empfängeraufruf blockiert die Sequenz. Netzwerkfehler, Timeouts und Nicht-2xx-Antworten folgen der gemeinsamen Retry-Regel; endgültige Fehler bleiben im Zustellverlauf. Eine 2xx-Antwort bedeutet HTTP-Annahme, nicht den Abschluss nachgelagerter Aktionen. Antwortinhalte werden verworfen.

Nach Beheben eines Fehlers kannst du zugestellte oder in Dead-Letter beendete Einträge im Schritt oder in der Webhook-Verwaltung erneut zustellen, bei aktivem Ziel und aktuellem Pro-/Workspace-Zugriff. Replay erzeugt eine weitere Zustellung des gespeicherten Snapshots; aktuelle Buchungs-/Kontaktdaten werden nicht neu gelesen und weder Flow noch E-Mails erneut ausgeführt.

Zwischen Flow-Schritten ist keine Reihenfolge der HTTP-Ankunft garantiert. Die Workspace-Abhängigkeit lead.captured → booking.created gilt nicht für flow.webhook. Eine spätere E-Mail oder ein späterer Webhook-Schritt kann vor dem Zustellerfolg eines früheren Webhooks fertig sein. Spätere Absage, Umbuchung oder Sequenzversionswechsel ziehen bereits übergebene Zustellungen nicht zurück.

Endpunktverträge und Zustellfilter einschließlich eventType=flow.webhook stehen in der generierten API-Referenz.

Auf dieser Seite