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:
| Feld | Bedeutung |
|---|---|
data.flow.sequence_id | Identität der Sequenz über Versionen hinweg. |
data.flow.version_id | Veröffentlichte Sequenzversion dieses Laufs. |
data.flow.node_id | Webhook-Knoten im Graphen dieser Version. |
data.flow.run_id | Sequenzlauf für diesen Termin. |
data.flow.step_id | Diese Schrittausführung; bei Retry und Replay unverändert. |
data.host | Host-ID und Anzeigename, ohne Host-E-Mail oder Anbieterdaten. |
data.funnel | ID 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.