API & Webhooks

Mit API & Webhooks arbeiten Ihre eigenen Systeme (ERP, Data Warehouse, Website-Backend, Automatisierungstools) mit Ihrem NextCRM-Workspace zusammen:

• die REST-API liest und ändert Leads, Kontakte, Aufgaben und Notizen und liest Funnels, Formulareinsendungen, Kampagnen und Teammitglieder;
• Webhooks benachrichtigen Ihren Server, sobald etwas passiert, zum Beispiel bei einem neuen Lead oder einem Phasenwechsel.

Hinweis: Nur Workspace-Admins können Einstellungen > API & Webhooks öffnen. API-Zugriff ist in den Tarifen Business, Agency und Enterprise enthalten. In anderen Tarifen bleiben vorhandene Schlüssel und Endpunkte sichtbar, neue können aber nicht angelegt werden und API-Aufrufe werden abgelehnt.

Wo Sie jeden Wert finden

Alles kommt aus NextCRM selbst; Sie brauchen kein Konto bei einem Drittanbieter.

Wert	Wo Sie ihn finden
API-Schlüssel	Einstellungen > API & Webhooks > API-Schlüssel erstellen. Der vollständige Schlüssel wird nur einmal angezeigt; kopieren Sie ihn als Bearer-Token in Ihre Integration (zum Beispiel n8n, Zapier, Make oder Ihren eigenen Code).
Signatur-Secret	Wird einmal angezeigt, wenn Sie einen Webhook-Endpunkt hinzufügen, und erneut nach Secret erneuern. Speichern Sie es auf dem Server, der die Webhooks empfängt.
Endpunkt-URL	Kommt aus Ihrem eigenen System oder Automatisierungstool, zum Beispiel die Produktions-URL eines n8n-Webhook-Knotens. Sie muss https verwenden.

Reihenfolge: API-Schlüssel mit den nötigen Berechtigungen erstellen > einen ersten Aufruf machen > einen Webhook-Endpunkt mit seinen Ereignissen hinzufügen > die Signatur auf Ihrem Server prüfen > ein Testereignis senden.

API-Schlüssel erstellen

1. Klicken Sie unten in der Seitenleiste auf Ihre Profilkarte, wählen Sie Einstellungen, öffnen Sie die Karte API & Webhooks (API & Webhooks öffnen) und bleiben Sie im Tab API-Schlüssel.
2. Klicken Sie auf API-Schlüssel erstellen.
3. Geben Sie einen Namen ein, an dem Sie erkennen, wo der Schlüssel genutzt wird, zum Beispiel „ERP-Synchronisation“.
4. Wählen Sie unter Berechtigungen pro Bereich Lesen und/oder Schreiben. Wählen Sie nur, was die Integration wirklich braucht.
5. Legen Sie optional unter Läuft ab ein Ablaufdatum fest (30, 90 oder 365 Tage oder ein Datum).
6. Klicken Sie auf Schlüssel erstellen und kopieren Sie den Schlüssel sofort mit Kopieren.

Achtung: Der Schlüssel wird nur einmal angezeigt. NextCRM speichert nur einen Fingerabdruck (Hash) davon, daher kann ihn niemand - auch nicht der Support - erneut anzeigen. Geht er verloren, widerrufen Sie ihn und erstellen Sie einen neuen.

Die Liste zeigt jeden Schlüssel mit seinem Präfix (zum Beispiel ncrm_live_1a2b3c4d), den Berechtigungen, wer ihn erstellt hat, wann er zuletzt genutzt wurde und wann er abläuft. Widerrufen sperrt einen Schlüssel sofort.

Was ein Schlüssel darf

Ein Schlüssel handelt für Ihren Workspace mit den Rechten eines Workspace-Admins, beschränkt auf die gewählten Berechtigungen:

Berechtigung	Erlaubt
Leads (Lesen / Schreiben)	Leads auflisten und lesen; anlegen, ändern, in eine Phase verschieben, zuweisen, in den Papierkorb verschieben und wiederherstellen
Kontakte (Lesen / Schreiben)	Kontakte auflisten, lesen, anlegen, ändern und löschen
Aufgaben (Lesen / Schreiben)	Aufgaben auflisten und lesen; anlegen, ändern, erledigen und archivieren
Funnels und Phasen (Lesen)	Funnels mit ihren Phasen lesen
Formulareinsendungen (Lesen)	Formulare und ihre Einsendungen lesen
Kampagnen (Lesen)	Kampagnen und ihre Ergebnisse lesen
Notizen und Aktivitäten (Lesen / Schreiben)	Notizen und Verlauf eines Leads lesen; Notizen hinzufügen und Anrufe protokollieren
Teammitglieder (Lesen)	Namen, E-Mails und Rollen der Teammitglieder lesen (um Leads und Aufgaben zuzuweisen)
Webhooks (Lesen / Schreiben)	Webhook-Endpunkte lesen, registrieren und löschen

Es gelten dieselben Regeln wie in der App: Tariflimits (ein neuer Lead über Ihrem Limit aktiver Leads landet in der Lead Inbox), der Papierkorb (Leads im Papierkorb müssen erst wiederhergestellt werden; Löschen über die API verschiebt immer in den Papierkorb), und Daten gelangen nie in einen anderen Workspace. Was nur Personen dürfen - Team, Rollen, Abrechnung oder API-Schlüssel verwalten und endgültig löschen - ist mit einem Schlüssel nicht möglich. Ein Schlüssel funktioniert außerdem nicht mehr, wenn die Person, die ihn erstellt hat, kein Workspace-Admin mehr ist.

Jede Änderung über einen Schlüssel erscheint im Lead-Verlauf als API key <Name>.

Der erste Aufruf

Senden Sie den Schlüssel im Header Authorization. Die Basis-URL ist https://…/api/v1.

curl https://…/api/v1/leads?limit=10 \
  -H "Authorization: Bearer ncrm_live_..."

Einen Lead anlegen:

curl -X POST https://…/api/v1/leads \
  -H "Authorization: Bearer ncrm_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f9c2a10-order-4711" \
  -d '{"first_name":"Ada","last_name":"Lovelace","email":"ada@example.com","value":12000}'

Die vollständige Referenz mit allen Endpunkten, Feldern und je einem curl-Beispiel finden Sie im Tab API-Dokumentation, öffentlich unter https://…/api/v1/docs und als OpenAPI-3.1-Datei unter https://…/api/v1/openapi.json.

Regeln für jede Integration

• Antworten haben die Form { "data": ..., "meta": { ... } }, Fehler { "error": { "code", "message", "details" } } mit einer Feldliste bei Validierungsfehlern. Datumswerte sind ISO 8601 in UTC.
• Seiten: Listen liefern meta.next_cursor; übergeben Sie ihn als cursor, um die nächste Seite zu laden (limit bis 100).
• Idempotenz: Senden Sie bei POST-Anfragen einen Idempotency-Key-Header. Eine Wiederholung mit demselben Schlüssel liefert das erste Ergebnis, statt ein Duplikat anzulegen (24 Stunden lang).
• Ratenlimits: 120 Anfragen pro Minute und Schlüssel und 600 pro Workspace. Darüber antwortet die API mit 429 und einem Retry-After-Header - warten Sie so viele Sekunden.
• Wartung: Während eines NextCRM-Updates antwortet die API mit 503 MAINTENANCE und Retry-After. Webhooks werden zurückgehalten und danach zugestellt.
• Nur vom Server: Rufen Sie die API von Ihrem Server aus auf. Browser können sie nicht aufrufen (kein CORS), und ein API-Schlüssel gehört nie in eine Website oder App.

Webhooks

1. Öffnen Sie den Tab Webhooks und klicken Sie auf Endpunkt hinzufügen.
2. Geben Sie die Endpunkt-URL Ihres Servers ein. Sie muss mit https:// beginnen und aus dem Internet erreichbar sein; interne, private und Cloud-Metadaten-Adressen werden abgelehnt.
3. Wählen Sie die gewünschten Ereignisse und klicken Sie auf Endpunkt speichern.
4. Kopieren Sie das Signatur-Secret (wird einmal angezeigt) und speichern Sie es auf Ihrem Server.
5. Klicken Sie auf Testereignis senden, um zu prüfen, ob Ihr Server antwortet.

Verfügbare Ereignisse: lead.created, lead.updated, lead.stage_changed, lead.assigned, lead.trashed, lead.restored, task.created, task.completed, form.submitted, contact.created, contact.updated, campaign.sent, call.logged, nps.responded, customer.renewal_updated, customer.at_risk, booking.created, booking.rescheduled, booking.canceled, quote.sent, quote.accepted, quote.declined und automation.webhook.

Angebotsereignisse enthalten Beträge als ganze Zahlen in der kleinsten Einheit der Währung (zum Beispiel Cent): subtotal_minor ist die Summe der Positionen nach Positionsrabatten, discount_minor der Rabatt auf das ganze Angebot, tax_minor die Steuer und total_minor der zu zahlende Betrag. total_minor einer Position ist ihr Betrag nach dem Positionsrabatt, vor dem Angebotsrabatt und der Steuer.

Leads aus einem Datei-Import senden nach Abschluss des Imports ein lead.created pro importiertem Lead, mit "context": { "source": "import", "import_batch_id": "..." } neben data.

Jede Zustellung ist ein POST mit dem Ereignis als JSON (id, type, created_at, actor, data) und diesen Headern: X-NextCRM-Event, X-NextCRM-Delivery, X-NextCRM-Timestamp und X-NextCRM-Signature.

Signatur prüfen

X-NextCRM-Signature sieht so aus: t=1760860800,v1=5f2b.... Berechnen Sie HMAC-SHA256 von <t>.<Rohdaten des Request-Body> mit Ihrem Signatur-Secret und vergleichen Sie das Ergebnis mit v1. Lehnen Sie Anfragen ab, deren Zeitstempel älter als 5 Minuten ist.

import crypto from "node:crypto";

function verify(rawBody, header, secret) {
  const t = Number(/(?:^|,)t=(\d+)/.exec(header)?.[1]);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return header.split(",").some((part) => part === `v1=${expected}`);
}

Wiederholungen, Zustellprotokoll und Erneuerung

• Antworten Sie innerhalb von 10 Sekunden mit einem beliebigen 2xx-Status. Andernfalls wiederholt NextCRM die Zustellung mit wachsenden Pausen (1, 2, 4, ... Minuten), bis zu 8 Versuche.
• Das Zustellprotokoll zeigt jede Zustellung mit Status, Versuchen und Antwortcode. Erneut senden plant eine Zustellung noch einmal ein.
• Nach vielen Fehlschlägen in Folge wird ein Endpunkt automatisch deaktiviert und alle Workspace-Admins erhalten eine Benachrichtigung. Beheben Sie das Problem und klicken Sie dann auf Aktivieren.
• Secret erneuern erstellt ein neues Signatur-Secret. Das alte signiert noch 24 Stunden lang mit, damit Sie ohne Ereignisverlust umstellen können.

Lora und die API

Lora kann die API erklären, diese Seite öffnen und Ihre Webhook-Endpunkte auflisten. Sie erstellt, zeigt oder widerruft niemals API-Schlüssel und sieht nie ein Signatur-Secret - das erledigen Sie selbst auf dieser Seite.

Fehlerbehebung

Antwort	Bedeutung
401 INVALID_API_KEY, API_KEY_REVOKED, API_KEY_EXPIRED	Der Schlüssel ist falsch, widerrufen oder abgelaufen. Erstellen Sie einen neuen.
403 INSUFFICIENT_SCOPE	Dem Schlüssel fehlt die Berechtigung für diesen Aufruf. Erstellen Sie einen Schlüssel mit der nötigen Berechtigung.
403 API_KEY_OWNER_NOT_ADMIN	Die Person, die den Schlüssel erstellt hat, ist kein Workspace-Admin mehr. Ein aktueller Admin muss einen neuen Schlüssel erstellen.
402 FEATURE_NOT_IN_PLAN	Der Tarif enthält keinen API-Zugriff.
409 LEAD_IN_TRASH	Stellen Sie den Lead zuerst wieder her (POST /leads/{id}/restore).
422 VALIDATION_FAILED	Feld und Grund stehen in error.details.
429 RATE_LIMITED	Warten Sie die Retry-After-Sekunden und machen Sie dann weiter.