Öffentliche API & Webhooks

Die öffentliche API und Webhooks verbinden Werkstube mit einem CRM, Shop, Portal oder eigenen Dienst. Die API liest oder ändert Daten auf Anfrage. Ein Webhook informiert deinen Dienst, wenn in Werkstube ein unterstütztes Ereignis eintritt.

#Voraussetzungen

Du brauchst:

• einen Tarif, in dem API & Webhooks freigeschaltet ist;
• das Recht API-Zugänge verwalten zum Anlegen eines API-Zugangs;
• API-Schlüssel rotieren, wenn ein Schlüssel erneuert werden muss;
• Webhooks verwalten zum Anlegen und Ändern eines Webhook-Ziels;
• Webhook-Zustellungen ansehen und Webhook-Zustellungen wiederholen für das Zustellprotokoll.

Wenn die Seite meldet, dass die Funktion für den aktuellen Tarif nicht freigeschaltet ist, kann der Zugang nicht selbst angelegt werden. Bitte die Administration, den passenden Tarif oder die Funktion freizuschalten. Fehlt nur ein Recht, muss die Administration dir das jeweilige Recht geben.

#API-Zugang anlegen

1. API-Seite öffnen

   Gehe zu Einstellungen → API & Webhooks.
2. Zugang benennen

   Trage unter Name einen eindeutigen Zweck ein, zum Beispiel „CRM-Synchronisation“.
3. Ablauf festlegen

   Setze optional ein Ablaufdatum. Ein kurzer, geplanter Gültigkeitszeitraum verringert das Risiko vergessener Zugänge.
4. Rechte auswählen

   Wähle nur die Scopes, die der Dienst wirklich benötigt.
5. Zugang erzeugen

   Klicke auf Zugang anlegen.
6. Schlüssel sicher speichern

   Der API-Schlüssel erscheint nur einmal in der Meldung API-Schlüssel – nur jetzt sichtbar. Kopiere ihn sofort in den sicheren Zugangsspeicher des angeschlossenen Dienstes.

Die Liste der auswählbaren Scopes kann je nach Berechtigung und Umgebung kleiner sein. Ein API-Zugang sollte immer einem einzelnen Dienst gehören. Teile den Schlüssel nicht mit Mitarbeitenden und speichere ihn nicht in Quelltext, Tickets oder Logdateien.

In der Tabelle darunter siehst du Präfix, Status, Scopes, verantwortliche Person und Ablaufdatum. Mit Schlüssel rotieren erzeugst du einen neuen Schlüssel. Stelle den angeschlossenen Dienst zuerst auf den neuen Schlüssel um und widerrufe den alten erst danach mit Widerrufen.

#Erste API-Anfrage prüfen

Die vollständige Spezifikation erreichst du in Werkstube über OpenAPI-Spezifikation öffnen. Für einen ersten Lesezugriff kannst du nach dem Einsetzen der Werkstube-Adresse und des Schlüssels etwa Folgendes verwenden:

curl "https://deine-werkstube.example/api/v1/customers?page_size=25" \
  -H "Authorization: Bearer wk_live_..."

Erwartest du eine erfolgreiche Antwort, prüfe zunächst Statuscode, Ergebnisliste und Seiteninformationen. Verwende für produktive Dienste immer HTTPS.

#API-Antworten, Seiten und Fehler

Listen werden seitenweise geliefert. Verwende die in der Antwort enthaltene Seiteninformation, statt immer dieselbe erste Seite abzurufen. Bei großen Datenmengen speichere den zuletzt verarbeiteten Stand im angeschlossenen Dienst.

Bei einem Fehler liefert Werkstube eine strukturierte Antwort mit:

{
  "error": {
    "code": "insufficient_scope",
    "message": "The API key does not grant the requested scope.",
    "request_id": "req_123",
    "fields": {}
  }
}

Die Request-ID gehört in ein Support-Ticket. Sie enthält keine Lösung, hilft aber bei der Suche nach dem konkreten fehlgeschlagenen Aufruf.

Aktuelle Begrenzungen:

• pro API-Prinzipal höchstens 120 Anfragen pro Minute;
• pro Mandant höchstens 3000 Anfragen pro Minute.

Beachte die Antwort-Header X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset und bei einer Sperre Retry-After. Warte bei Status 429 bis zum angegebenen Zeitpunkt und sende die Anfrage dann erneut mit Verzögerung.

#Sicher schreiben

Bei POST- und PATCH-Anfragen solltest du einen stabilen Idempotenzschlüssel verwenden. Derselbe Schlüssel schützt innerhalb von 24 Stunden davor, dass ein Netzwerkfehler zu einer doppelten Anlage führt. Verwende für einen fachlich neuen Vorgang einen neuen Schlüssel.

Beim Ändern vorhandener Datensätze kann Werkstube zusätzlich einen ETag zurückgeben. Sende diesen Wert in If-Match, damit du nicht versehentlich eine Änderung überschreibst, die zwischen Lesen und Schreiben durch jemand anderen erfolgt ist.

Typische Antworten:

#Webhook-Ziel einrichten

Ein Webhook benötigt einen öffentlich erreichbaren HTTPS-Endpunkt, der die Werkstube-Anfrage schnell bestätigt, die Signatur prüft und die Verarbeitung danach zuverlässig ausführt. Leite die Anfrage nicht über eine ungeschützte HTTP-Adresse weiter.

1. Ziel öffnen

   Gehe zu Einstellungen → API & Webhooks und scrolle zum Bereich für Webhook-Ziele.
2. URL eintragen

   Trage bei Name des Ziels einen Zweck und bei der URL eine Adresse ein, die mit https:// beginnt.
3. Ereignisse auswählen

   Wähle nur benötigte Ereignisse: customer.created, customer.updated, job.created, job.updated, appointment.created, appointment.updated oder endpoint.test. Alle Ereignisse nutzt du nur, wenn der Dienst sie tatsächlich verarbeiten kann.
4. Ziel anlegen

   Klicke auf Webhook anlegen.
5. Secret sichern

   Das Signatur-Secret erscheint nur einmal. Speichere es im sicheren Zugangsspeicher des empfangenden Dienstes.

Ein Ziel kannst du mit Bearbeiten ändern, mit Deaktivieren vorübergehend ausschalten und mit Aktivieren wieder einschalten. Mit Secret rotieren erzeugst du ein neues Signatur-Secret. Stelle zuerst auf das neue Secret um; das alte bleibt für einen kurzen Übergang gültig.

#Webhook-Signatur prüfen

Jede Zustellung ist mit HMAC-SHA-256 signiert. Prüfe die Signatur vor jeder Verarbeitung mit dem unveränderten Request-Body. Die wichtigen Header sind:

• X-Werkstube-Signature mit der Signatur;
• X-Werkstube-Timestamp gegen zu alte oder wiederholte Anfragen;
• X-Werkstube-Event-Id zur Erkennung bereits verarbeiteter Ereignisse;
• X-Werkstube-Key-Id zur Auswahl des passenden Secrets.

Die signierte Zeichenkette lautet:

v1.<unix_timestamp>.<event_id>.<raw_body>

Berechne HMAC-SHA-256 mit dem Webhook-Secret, vergleiche den Wert zeitkonstant und verarbeite das Ereignis nur bei gültigem Zeitstempel und gültiger Signatur. Speichere die Event-ID für die Dauer deiner eigenen Duplikaterkennung. Die Nutzlast enthält die Ereignisinformation; für den vollständigen aktuellen Datensatz kann dein Dienst anschließend die API aufrufen.

Ein Beispiel für die Prüfung in Node.js:

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyWerkstubeWebhook({ body, timestamp, eventId, signature, secret }) {
  const signed = "v1." + timestamp + "." + eventId + "." + body;
  const expected = createHmac("sha256", secret).update(signed).digest("hex");
  const received = Buffer.from(signature.replace(/^v1=/, ""), "utf8");
  const calculated = Buffer.from(expected, "utf8");

  return received.length === calculated.length && timingSafeEqual(received, calculated);
}

Verwende in deiner Anwendung zusätzlich eine Zeitprüfung und eine Liste bereits verarbeiteter Event-IDs. Ein erfolgreich angenommener HTTP-Status sollte schnell zurückgegeben werden; die eigentliche Verarbeitung kann danach erfolgen.

#Zustellungen prüfen und wiederholen

Im Bereich Zustellprotokoll kannst du mit Alle Ziele oder einem einzelnen Ziel filtern. Prüfe Ereignis, Status, HTTP-Code, Versuch, Zeitpunkt und Antwortauszug.

Werkstube versucht fehlgeschlagene Zustellungen ungefähr nach 1, 5 und 15 Minuten sowie nach 1, 4, 12 und 24 Stunden erneut. Nach acht Versuchen landet ein Ereignis im Status dead. Für dead oder delivered ist Wiederholen verfügbar, sofern du das Recht Webhook-Zustellungen wiederholen hast.

Wiederhole erst, nachdem dein Endpunkt den Fehler behoben hat. Bei einer erfolgreichen Zustellung muss dein Dienst die Event-ID trotzdem gegen doppelte Verarbeitung schützen.

#Häufige Fehler

#Offizielle technische Hilfe

• OpenAPI-Spezifikation in Werkstube öffnen
• OpenAPI-Spezifikation 3.1

Die in Werkstube verlinkte OpenAPI-Datei ist die maßgebliche Quelle für Endpunkte, Felder und aktuelle Antwortmodelle. Diese Anleitung erklärt den sicheren Einrichtungsweg; bei einer Abweichung hat die Spezifikation Vorrang.