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
- Name: woran Sie den Webhook erkennen, zum Beispiel „Buchhaltung“.
- Adresse: die öffentliche https-Adresse Ihrer Software. Octoserv sendet dort einen POST mit JSON.
- Ereignisse: eine Art (
contact.created), eine Familie (deal.*) oder eine Sorte (*.created). Die Auswahlliste zeigt, was es gibt. - Konto: bestimmt, was der Webhook bekommt. Er sieht nur Datensätze und Felder, die dieses Konto sehen und lesen darf. Für Anbindungen wählen Sie ein Dienstkonto mit genau den Rechten, die die Anbindung braucht.
- Filter: nur für bestimmte Arten von Datensätzen oder nur, wenn sich bestimmte Felder geändert haben.
- Schlank: sendet nur, was sich geändert hat, ohne den ganzen Datensatz.
- Automatische Einträge: Einträge, die das System selbst macht, etwa bei einem Import, werden nur gesendet, wenn Sie das einschalten.
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.
- Es hat kein Passwort und meldet sich nie am Bildschirm an.
- Es zählt nicht als Benutzer und nicht gegen die Höchstzahl der Benutzer.
- Es arbeitet mit Token. Ein Token wirkt wie das Token einer Person mit den Rechten der Rollen des Kontos.
- Was es tut, steht mit seinem Namen im Journal.
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.
- Derselbe Schlüssel mit einer anderen Anfrage wird abgewiesen (
422, Codeidempotency_key_reused). - Läuft die erste Anfrage noch, antwortet Octoserv mit
409.
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.
Für Websites, die öffentliche Formulare senden, gibt es unter Einstellungen › API-Keys die Website-Schlüssel:
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.
- Grenzen: höchstens 20 Webhooks je Octoserv, die Lieferungen bleiben 30 Tage im Protokoll, Octoserv wartet je Aufruf höchstens 10 Sekunden auf die Antwort. Die Adresse muss https und öffentlich erreichbar sein.
- Reihenfolge: Zu einem Datensatz werden die Meldungen in der Reihenfolge der Ereignisse gesendet; eine spätere wartet auf die frühere.
- Mindestens einmal: Ihre Software kann dieselbe Meldung mehr als einmal bekommen. Sieht sie dieselbe
webhook-idzweimal, ignoriert sie die zweite. - Datensätze: Der Inhalt eines Datensatzes kommt nur für Kontakte, Firmen und Deals, und nur mit den Rechten und Feldrechten des gewählten Kontos. Bei anderen Arten nennt die Meldung nur das Ereignis. Ist der Datensatz größer als 256 KB, entfallen die vollständigen Angaben, und
truncated: truesteht in der Meldung. - Pause: Der Eigner des Webhooks bekommt bei einer Pause eine Aufgabe und eine Mail. Die Ereignisse während der Pause werden weiter vorgemerkt und nach dem Einschalten der Reihe nach nachgeliefert, nichts geht verloren.
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
- Lesen Sie die drei Kopfzeilen
webhook-id,webhook-timestampundwebhook-signature. - Weisen Sie die Anfrage ab, wenn der Zeitstempel mehr als 5 Minuten von Ihrer Uhr abweicht.
- Bilden Sie den Text
id.zeitstempel.inhaltaus der Id, dem Zeitstempel und dem unveränderten Inhalt der Anfrage. - Berechnen Sie davon den HMAC-SHA256 mit Ihrem Signaturschlüssel (der Teil nach
whsec_ist Base64-kodiert) und kodieren Sie das Ergebnis mit Base64. - Vergleichen Sie es mit dem Wert hinter
v1,inwebhook-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
- Flow-Editor: Der Schritt Webhook ruft Systeme aus einem Flow auf, der Auslöser Webhook-Empfänger nimmt Anfragen von außen an.
- Connector: bindet ein anderes System mit seinem Datenbestand an.
- KI-Dienst: Agenten-Zugang und Rollen und Rechte: Token wirken mit den Rechten ihres Kontos.
- Journal: Jede Änderung an einem Webhook und alles, was ein Dienstkonto tut, steht dort.