API & programmatischer Zugriff

Wie fremde Systeme mit der Plattform sprechen: MCP für Automatisierung, Webhooks für eingehende Daten — und was ausdrücklich kein API ist.

Wie fremde Systeme mit der Plattform sprechen — und wie nicht.

Die kurze Antwort: Für Automatisierung und eigenen Code ist MCP der Zugang; für eingehende Daten aus Drittsystemen der Webhook-Eingang. Die Routen der Web-App (/api/app/...) sind kein öffentliches API und lassen sich von außen nicht nutzen.

1. MCP — der programmatische Zugang

Ein Endpunkt pro Workspace, der die gesamte Tool-Fläche trägt (dieselben Funktionen, die die Oberfläche benutzt):

https://app.cegtec.net/api/mcp/<workspace-mcp-key>

Key erzeugen/abrufen: in den Einstellungen des Workspace oder über die Tools generate_mcp_key / get_mcp_key. Der Key ist workspace-gebunden — er kann nichts außerhalb dieses Workspace sehen oder verändern.

MCP-Clients gibt es für die meisten Umgebungen (Claude, Claude Code, eigene Skripte, n8n). Die vollständige Tool-Liste steht in der MCP-Tool-Referenz.

Warum MCP und nicht REST: die Tool-Fläche ist die eine Definition dessen, was die Plattform kann — Oberfläche und Agenten benutzen sie gleichermaßen. Eine parallele REST-Fläche wäre eine zweite Wahrheit, die auseinanderdriftet.

2. Webhook-Eingang für eigene Daten

Der generische Dateneingang — hier schicken Sie Zeilen aus einem beliebigen System (Formular, Zapier, Make, eigenes Backend) in einen Workspace:

POST https://app.cegtec.net/api/webhooks/ingest/<orgId>/<sourceId>

Authentifizierung: ein Shared Secret pro Quelle, entweder als Header x-webhook-secret: <secret> oder als Query-Parameter ?secret=<secret> — die Query-Variante existiert für No-Code-Werkzeuge, die keine Header setzen können. Fehlt oder passt das Secret nicht: 401. Ist die Quelle deaktiviert: 403.

Angelegt wird eine solche Quelle über create_webhook_source; dabei entstehen sourceId und Secret.

Was mit den Daten passiert: sie werden auf die Ontologie gemappt (Firma bzw. Lead) und können einen Workflow auslösen — das ist Teil der Quellen-Konfiguration, nicht des Requests.

3. Provider-Webhooks

Rückkanäle der angebundenen Dienste. Diese richtet die Plattform ein, wenn Sie eine Integration verbinden — Sie rufen sie nicht selbst auf. Sie sind hier nur der Vollständigkeit wegen aufgeführt:

Zweck	Pfad
E-Mail-Versand (Öffnungen, Antworten, Bounces)	`/api/webhooks/instantly`
LinkedIn	`/api/webhooks/heyreach`, `/api/webhooks/unipile`
Generischer Kanal-Rückkanal	`/api/webhooks/channels`
Kalender (Buchungen)	`/api/webhooks/calendar`
Abrechnung	`/api/webhooks/stripe`
Firmendaten-Zulieferung	`/api/webhooks/companies`
Telefonie / Sprach-Agent	`/api/webhooks/twilio/`, `/api/webhooks/elevenlabs/`

Jeder dieser Endpunkte prüft die Herkunft (Signatur, Secret oder Token) — mit einer dokumentierten Ausnahme, siehe unten.

4. Was kein API ist

/api/app/<orgSlug>/... — die Routen der Web-App. Sie sind session-authentifiziert: sie erwarten das Anmelde-Cookie des Browsers und prüfen zusätzlich die Herkunft des Requests (Origin-Check). Ein Aufruf mit curl, aus n8n oder aus eigenem Code schlägt fehl, auch mit gültigem Login — das ist Absicht und kein Fehler. Für alles Programmatische: MCP (Abschnitt 1).

/api/cron/... und /api/admin/... — interne Betriebsendpunkte, abgesichert über ein geteiltes Secret. Nicht für Kunden bestimmt.

Bekannte Einschränkungen

/api/webhooks/heyreach verifiziert die Herkunft nicht (Stand 2026-08-05). Der Workspace wird aus der Kampagnen-ID der Nutzlast aufgelöst; wer URL und eine gültige Kampagnen-ID kennt, kann Antwort-Ereignisse einliefern. Folgen: Lead-Status, Antwort-Queue, Deal-Anlage und ein Credit-Verbrauch durch die Antwort-Klassifizierung. Ein Pflicht-Secret würde bestehende, produktiv laufende Webhooks unterbrechen — die Umstellung ist deshalb koordiniert mit dem Neu-Einrichten auf Anbieterseite zu machen, nicht einseitig.
Keine öffentliche REST-Fläche für die Kern-Objekte. Firmen, Leads und Deals sind programmatisch über MCP erreichbar, nicht über HTTP-Endpunkte mit API-Key. Sollte sich das ändern, gehört es hierhin.
Kein OpenAPI-Schema, da es keine öffentliche REST-Fläche gibt. Die MCP-Tools tragen ihre Parameter-Schemata selbst und sind für Clients auslesbar.

Zurück Lernschleifen