Webhooks und API

Octoserv lässt sich mit anderer Software verbinden, auf zwei Wegen: Octoserv meldet ein Ereignis an Ihre Software (Webhook), oder Ihre Software fragt bei Octoserv nach und ändert Daten (API). Diese Seite erklärt beide Wege, die Zugangsschlüssel und die Regeln, die für jede Anfrage gelten.

Ereignis-Webhooks

Mit einem Webhook meldet Octoserv ein Ereignis an Ihre andere Software, sobald es eintritt: ein Kontakt wurde angelegt, ein Deal wurde verschoben, ein Tag wurde gesetzt. Ihre Software muss nicht nachfragen, sie wird benachrichtigt. Beispiel: Ihre Buchhaltung bekommt sofort Bescheid, wenn ein Deal auf „gewonnen“ springt, und legt den Kunden an.

Webhook anlegen

Gleich nach dem Anlegen zeigt Octoserv den Signaturschlüssel, einmal und nie wieder. Kopieren Sie ihn in Ihre Software. Geht er verloren, erzeugen Sie einen neuen.

Die Anfrage prüfen

Jede Anfrage trägt die Kopfzeilen webhook-id, webhook-timestamp und webhook-signature nach dem Standard „Standard Webhooks“. Ihre Software rechnet die Signatur mit dem Schlüssel nach und weiß so, dass die Anfrage von Ihrem Octoserv kommt und nicht verändert wurde. Eine Anfrage, die älter als fünf Minuten ist, weisen Sie ab. Die webhook-id bleibt bei einer Wiederholung gleich, so erkennen Sie doppelte Lieferungen. Antwortet Ihre Software mit einem Status 2xx, gilt die Lieferung als angekommen.

Wenn etwas schiefgeht

Antwortet Ihre Software nicht oder mit einem Fehler, versucht es Octoserv nach 1 Minute, 5 Minuten, 15 Minuten, 1, 3, 6 und 12 Stunden noch einmal. Klappt auch der letzte Versuch nicht, wird der Webhook pausiert, und der Administrator bekommt eine Aufgabe und eine Mail. Antwortet Ihre Software mit 410, gibt es sie nicht mehr; der Webhook wird sofort pausiert. Nach der Reparatur schalten Sie ihn mit Einschalten wieder ein; die Ereignisse der Pause werden dann nachgeliefert.

Test und Protokoll

Test senden schickt eine Testlieferung, die Ihre Software wie eine echte prüft. Unter Lieferungen sehen Sie die letzten 30 Tage: Zustand, Zahl der Versuche, die Antwort und den nächsten Versuch. Erneut senden schickt eine einzelne Lieferung noch einmal. Im Protokoll stehen nur die Art des Ereignisses, der Datensatz und der Zustand, keine Inhalte.

Abfragen statt Zuhören

Wer lieber abfragt, ruft in der API GET /api/v1/events?after= auf und bekommt alle Ereignisse seit der letzten Abfrage.

Rechte

Die Seite sehen und ändern nur Benutzer mit dem Recht Webhooks. Es gibt Ereignisse, die nie gesendet werden, zum Beispiel Anmeldungen und Schlüssel. Jede Änderung an einem Webhook steht im Journal.

Webhook aus einem Flow signieren

Auch der Schritt Webhook im Flow-Editor kann seine Anfrage signieren. Schalten Sie Anfrage signieren ein: Die Anfrage trägt dann dieselben drei Kopfzeilen. Der Schlüssel entsteht beim Speichern des Schritts und wird einmal angezeigt; Neuer Schlüssel ersetzt ihn. Eine wiederholte Anfrage hat dieselbe webhook-id.

Die API

Die API ist für Software gedacht, die Daten in Octoserv liest oder ändert, zum Beispiel Ihre Website, die Anfragen als Kontakte anlegt. Sie erreichen sie unter /api/v1/. Die Beschreibung aller Wege als OpenAPI-Datei steht unter /api/v1/openapi.json; sie wird aus dem Programm selbst erzeugt und enthält auch Ihre eigenen Felder bei Kontakten und Firmen.

Zugang: Token, Dienstkonten und Website-Schlüssel

Dienstkonten

Ein Dienstkonto ist ein Zugang für andere Software, keine Person. Beispiel: Ihre Website soll Anfragen als Kontakte in Octoserv anlegen. Dafür legen Sie ein Dienstkonto „Website-Formular“ an und geben ihm nur die Rolle, die das Anlegen von Kontakten erlaubt. Gerät der Zugang in falsche Hände, kann damit nicht mehr geschehen als diese eine Aufgabe.

Klicken Sie unter Einstellungen › Dienstkonten auf Dienstkonto anlegen, geben Sie einen Namen und die Rollen; geben Sie nur, was die Anbindung braucht. Danach erzeugen Sie ein Token mit einem Namen, einer Laufzeit (30 oder 90 Tage, 6 oder 12 Monate oder ohne Ende) und, wenn Sie wollen, einer Adressliste (siehe unten). Das Token erscheint nur einmal ganz. Kopieren Sie es und senden Sie es als Kopfzeile Authorization: Bearer <Token>. Geht es verloren, widerrufen Sie es und erzeugen ein neues. Beim Löschen eines Dienstkontos funktionieren alle seine Token sofort nicht mehr; was das Konto getan hat, bleibt im Journal. Die Seite sehen und ändern nur Benutzer mit dem Recht Dienstkonten.

Token nur von bestimmten Adressen

Beim Anlegen eines Tokens können Sie eine Liste von Adressen oder Netzen eintragen, zum Beispiel 203.0.113.7 oder 198.51.100.0/24. Das Token funktioniert dann nur von dort; aus einer anderen Adresse wird es abgewiesen. Leer heißt von überall.

Website-Schlüssel

Eine Website, die öffentliche Formulare an Ihr Octoserv sendet, braucht einen Website-Schlüssel. Sie legen ihn unter Einstellungen › API-Schlüssel mit einem Namen und den Websites an, die ihn nutzen dürfen (eine pro Zeile, mit https://). Nur diese Websites werden angenommen. Der Schlüssel erscheint nur einmal ganz, gleich nach dem Anlegen. Mit Websites ändern Sie die erlaubten Websites, mit Widerrufen nehmen Sie den Schlüssel außer Betrieb. Ein widerrufener Schlüssel bleibt in der Liste und lässt sich nicht wieder einschalten.

Ratenlimit

Die API bremst Anfragen pro Token und Minute. Vorgabe: 600 lesende und 120 schreibende je Token, insgesamt 6000 für den ganzen Mandanten. Darüber antwortet sie mit 429 und nennt in der Kopfzeile Retry-After, wie viele Sekunden Sie warten müssen. Die Oberfläche und jedes angeschlossene System zählen mit. Die Grenzen je Mandant ändert der Octoserv-Admin.

Beispiel: Ihr Import-Skript bekommt 429 mit Retry-After: 20. Es wartet 20 Sekunden und macht dann weiter.

Idempotenz: Doppelte Anfragen vermeiden

Bricht die Verbindung ab, weiß Ihre Software nicht, ob Octoserv die Anfrage bekommen hat. Schicken Sie bei jedem POST eine Kopfzeile Idempotency-Key mit einem eigenen Wert (bis 128 Zeichen). Octoserv führt die Anfrage dann einmal je Person und Schlüssel innerhalb von 24 Stunden aus. Wiederholen Sie dieselbe Anfrage, bekommen Sie die gespeicherte Antwort noch einmal, mit der Kopfzeile Idempotent-Replayed: true.

Beispiel: Ihre Kasse legt einen Kontakt an und schickt den Schlüssel kasse-2026-11-01-0815. Der Aufruf wird wegen eines Netzfehlers wiederholt; es entsteht trotzdem nur ein Kontakt.

Veränderungen bemerken: ETag und If-Match

Die Antwort auf das Lesen eines einzelnen Datensatzes trägt einen ETag. Schicken Sie ihn beim Ändern (PATCH, PUT) oder Löschen als If-Match zurück, ändert Octoserv den Datensatz nur, wenn er sich seitdem nicht geändert hat; sonst antwortet es mit 412. So überschreibt Ihre Software keine Änderung, die ein Kollege inzwischen gemacht hat. Mit If-None-Match beim Lesen bekommen Sie 304, wenn sich nichts geändert hat.

Versionen und Abkündigung

Die API trägt die Version v1; die Kopfzeile X-Octo-Api-Version nennt sie. Innerhalb der Version kommt nur Neues dazu. Was wegfällt, kündigt Octoserv mindestens zwölf Monate vorher mit den Kopfzeilen Deprecation und Sunset an, und die OpenAPI-Datei markiert den Weg.

Token und Schlüssel in der Oberfläche

Jeder Benutzer legt unter Einstellungen › Profil eigene API-Tokens an. Ein Token wirkt wie Sie selbst und kann nie mehr, als Sie dürfen. Es erhält entweder alle Ihre Rechte oder nur die, die Sie auswählen; es gilt höchstens 12 Monate und wird nur einmal angezeigt. Ein Token mit nur einigen Rechten kann keine weiteren Tokens erstellen. Widerrufen beendet es sofort und lässt sich nicht rückgängig machen.

Liste Meine API-Tokens mit Name, Token-Anfang, Rechten, Ablauf, Zuletzt benutzt, Status und dem Knopf Widerrufen
Meine API-Tokens im Profil
Fenster Neues API-Token mit Name, Ablaufdatum und der Wahl zwischen Alle meine Rechte und Nur die Rechte, die ich wähle
Ein neues Token mit einzelnen Rechten

Für Websites, die öffentliche Formulare senden, gibt es unter Einstellungen › API-Keys die Website-Schlüssel:

Karte Website-Schlüssel mit zwei Schlüsseln, einem widerrufenen und einem aktiven mit erlaubten Websites, und den Feldern Name und Websites zum Anlegen
Website-Schlüssel mit den erlaubten Websites

Webhooks: Inhalt, Grenzen und Einrichtung im Detail

Die Seite finden Sie unter Einstellungen › Webhooks. Sie legen einen Webhook mit Neuer Webhook an, wählen Name, Adresse, Ereignisse, Konto, Filter und die Schalter Schlank und Automatische Einträge und kopieren danach den Signaturschlüssel. Test senden, Lieferungen, Erneut senden und Einschalten sind an der Karte des Webhooks.

Beispiele mit Anfrage und Antwort

Eine Meldung bei einem neuen Kontakt

Die Buchhaltung der Muster GmbH hat einen Webhook mit dem Ereignis contact.created angelegt. Wird ein Kontakt angelegt, sendet Octoserv:

POST https://buchhaltung.beispiel.de/hooks/octoserv
Content-Type: application/json
webhook-id: 7f3c...
webhook-timestamp: 1790844000
webhook-signature: v1,K5oZfzN0...

{
  "type": "contact.created",
  "schema_version": 1,
  "id": "7f3c...",
  "timestamp": "2026-11-01T09:00:00+01:00",
  "data": {
    "object": { "id": "...", "type": "contact" },
    "actor": { "type": "user", "user_id": "..." },
    "source": "...",
    "description": "...",
    "record": { ... }
  }
}

Das Feld record (der Datensatz mit den Feldern, die das Konto des Webhooks lesen darf) und payload fehlen bei einem schlanken Webhook. Bei einer Änderung eines Feldes enthält data zusätzlich change mit dem Feld, dem alten und dem neuen Wert. Ihre Software antwortet mit 200; jeder Status 2xx gilt als angekommen. Nach einem Fehler folgt der nächste Versuch nach 1, 5 und 15 Minuten, dann nach 1, 3, 6 und 12 Stunden.

Die Signatur prüfen

  1. Lesen Sie die drei Kopfzeilen webhook-id, webhook-timestamp und webhook-signature.
  2. Weisen Sie die Anfrage ab, wenn der Zeitstempel mehr als 5 Minuten von Ihrer Uhr abweicht.
  3. Bilden Sie den Text id.zeitstempel.inhalt aus der Id, dem Zeitstempel und dem unveränderten Inhalt der Anfrage.
  4. Berechnen Sie davon den HMAC-SHA256 mit Ihrem Signaturschlüssel (der Teil nach whsec_ ist Base64-kodiert) und kodieren Sie das Ergebnis mit Base64.
  5. Vergleichen Sie es mit dem Wert hinter v1, in webhook-signature. Stimmt er überein, kommt die Anfrage von Ihrem Octoserv.

Für viele Programmiersprachen gibt es fertige Bibliotheken für den Standard „Standard Webhooks“.

Einen Kontakt per API anlegen

Die Website der Muster GmbH legt Anfragen als Kontakt an. Der Zugang ist ein Dienstkonto mit nur dem Recht, Kontakte anzulegen:

POST https://octo.beispiel.de/api/v1/contacts
Authorization: Bearer osn_...
Idempotency-Key: anfrage-2026-11-01-0815
Content-Type: application/json

{ "first_name": "Erika", "last_name": "Beispiel", "email": "erika.beispiel@example.com" }
HTTP/1.1 201 Created
RateLimit-Limit: 120
RateLimit-Remaining: 119
RateLimit-Reset: 41

{ "data": { "id": "...", "first_name": "Erika", "last_name": "Beispiel", ... } }

Wird dieselbe Anfrage mit demselben Idempotency-Key wiederholt, antwortet Octoserv mit derselben Antwort und der Kopfzeile Idempotent-Replayed: true. Es entsteht kein zweiter Kontakt. Alle Antworten der API verpacken ihren Inhalt in data.

Zu viele Anfragen

HTTP/1.1 429 Too Many Requests
Retry-After: 20

{ "status": 429, ... }

Jede Antwort nennt mit RateLimit-Limit, RateLimit-Remaining und RateLimit-Reset die Grenze, den Rest und die Sekunden bis zum Zurücksetzen. Ein Skript wartet bei 429 die Zeit aus Retry-After und macht dann weiter.

Nichts überschreiben

GET /api/v1/contacts/{id}      ->  ETag: "a1b2c3"
PATCH /api/v1/contacts/{id}
If-Match: "a1b2c3"             ->  412 Precondition Failed, wenn der Kontakt inzwischen geändert wurde

Bei 412 lesen Sie den Datensatz neu und entscheiden, was gelten soll.

Ereignisse abfragen statt zuhören

GET /api/v1/events?after={Id des letzten bekannten Ereignisses}

Die Antwort enthält die Einträge nach diesem Ereignis, aufsteigend, höchstens 500 je Abfrage. Fragen Sie mit der Id des letzten Eintrags erneut ab, bis nichts mehr kommt.

OpenAPI-Beschreibung

Die Datei unter /api/v1/openapi.json beschreibt alle Wege der API nach OpenAPI 3.1. Octoserv erzeugt sie aus dem Programm selbst; sie enthält auch Ihre eigenen Felder bei Kontakten und Firmen und markiert Wege, die wegfallen sollen. Laden Sie sie in ein Werkzeug für Schnittstellen, um Anfragen auszuprobieren oder Code zu erzeugen.

Zusammenspiel mit anderen Funktionen