API-Schlüssel und Webhooks einrichten

• FürAdministratoren
• ModulPublic API & Webhooks (im Paket Komplett+ oder als Zusatz)

Gilt ab Work7 0.10.0 · Stand 29.10.2026

Andere Programme können mit Work7 sprechen: Ein API-Schlüssel erlaubt einem Programm, Daten aus eurem Betrieb zu lesen oder zu schreiben, zum Beispiel eine Anfrage aus dem Website-Formular anzulegen. Ein Webhook dreht die Richtung um: Work7 meldet dem anderen Programm, dass etwas passiert ist, etwa dass ein Regiebericht abgeschlossen oder eine Rechnung bezahlt wurde. Beides richtest du an einer Stelle ein. Die technische Seite für Entwickler steht im Quickstart, unter Authentifizierung und Scopes und unter Webhooks; diese Anleitung zeigt dir die Einstellungen aus Sicht des Betriebs.

Wo du es findest

Einstellungen › Integrationen & Daten › Integrationen, dann der Reiter API & Webhooks. Er enthält drei Abschnitte: API-Schlüssel, Ausgehende Webhooks und, unter den Webhooks, Letzte Zustellungen.

• Ansehen dürfen Administratoren und Manager.
• Anlegen, widerrufen, pausieren und löschen dürfen nur Administratoren. Für Manager fehlen diese Knöpfe.
• Gehört das Modul nicht zu eurem Paket, steht dort stattdessen „… ist in eurem Work7-Paket nicht freigeschaltet“ mit einem Link auf Mehr erfahren. Vorhandene Einstellungen bleiben erhalten.

Oben auf der Seite erinnert ein Hinweis an die Grundlagen: Programme sprechen die Schnittstelle unter /api/v1 an und tragen den Schlüssel im Header Authorization: Bearer w7_….

Einen API-Schlüssel anlegen

1. Im Abschnitt API-Schlüssel gibst du einen Namen ein. Benenne den Schlüssel nach dem Programm, das ihn bekommt, zum Beispiel „Buchhaltung“ oder „Website-Formular“.
2. Hake die Berechtigungen an, die das Programm braucht. Sie heißen <bereich>:read (lesen) und <bereich>:write (lesen und schreiben), zum Beispiel inquiries:write für das Anlegen von Anfragen oder invoices:read zum Lesen von Rechnungen. Angeboten werden nur Bereiche, die euer Betrieb gebucht hat. Welcher Bereich was freigibt, steht unter Authentifizierung und Scopes.
3. Schlüssel erstellen wird aktiv, sobald ein Name und mindestens eine Berechtigung gewählt sind.
4. Work7 zeigt den Schlüssel jetzt ein einziges Mal in einem gelben Kasten an: „API-Schlüssel … jetzt kopieren, wird nicht erneut angezeigt.“ Mit Kopieren legst du ihn in die Zwischenablage und trägst ihn im anderen Programm ein. Schließen blendet den Kasten aus.

Work7 speichert den Schlüssel selbst nicht im Klartext. Hast du ihn nicht kopiert, legst du einen neuen an und widerrufst den alten.

Die Liste zeigt je Schlüssel den Namen, den Anfang des Schlüssels (er beginnt mit w7_live_ in der Produktivumgebung und mit w7_test_ in einer Testumgebung, so fällt ein vertauschter Schlüssel auf), die Berechtigungen und zuletzt verwendet am, oder „noch nie verwendet“.

Gut zu wissen:

• Ein Schlüssel gehört zu eurem Betrieb und sieht nie Daten anderer Betriebe.
• Was ein Programm per Schlüssel anlegt oder ändert, wird dem Administrator zugeordnet, der den Schlüssel erstellt hat.
• Vergib nur die Berechtigungen, die das Programm wirklich braucht, und einen eigenen Schlüssel je Programm. Schlüssel gehören nie in eine Webseite oder mobile App, sondern auf euren Server.

Kontakte und Projekte per Schlüssel verwalten

Mit der Berechtigung core:write darf ein Programm Kontakte und Projekte anlegen und ändern: einen Kunden samt Ansprechpartnern erfassen, Adressen und Telefonnummern ergänzen, ein Projekt zu einem Kunden anlegen, seinen Status wechseln oder es archivieren. core:read erlaubt nur das Lesen. Die Berechtigung gilt in jedem Paket.

• Archivieren und Löschen: Ein Kontakt lässt sich per Schlüssel archivieren oder löschen, aber nur, wenn nichts daran hängt. Hat er noch offene Vorgänge (Entwürfe von Angeboten oder Rechnungen, offene Rapporte, laufende Projekte, Anfragen), lehnt Work7 das ab und ändert nichts. Räume diese Vorgänge dann in Work7 auf; dort werden sie beim Archivieren oder Löschen eines Kontakts mitgenommen. Hat ein Kontakt bereits versendete Belege, lässt er sich nicht löschen, nur archivieren.
• Projekte werden nie gelöscht, sondern archiviert. Das Programm setzt dazu den Status auf „archiviert“, genau wie du es in Work7 tust.
• Wiederholte Aufrufe: Schickt ein Programm denselben Auftrag nach einem Netzwerkfehler erneut, legt es keinen zweiten Kontakt oder kein zweites Projekt an, sofern es einen Wiederholungsschutz mitsendet (Einzelheiten unter Fehler und Limits).
• Zuordnung: Neue Kontakte und Projekte tragen als Herkunft „API“, die Änderungen gehen auf den Administrator, der den Schlüssel erstellt hat. Ein neues Projekt braucht einen vorhandenen Kunden; die Projektnummer vergibt Work7, wenn das Programm keine mitschickt.
• Tempo: Ein Schlüssel darf höchstens 60 ändernde Aufrufe pro Minute senden. Darüber antwortet Work7 mit einer Wartemeldung.

Einen Schlüssel widerrufen

Ist ein Programm nicht mehr im Einsatz, oder ist ein Schlüssel verloren oder weitergegeben worden: In der Liste auf Widerrufen neben dem Schlüssel klicken. Das gilt sofort und ohne Rückfrage. Das Programm bekommt danach nur noch Fehlermeldungen, der Eintrag bleibt durchgestrichen in der Liste stehen, und Work7 bietet keinen Knopf, ihn wiederherzustellen. Braucht das Programm weiter Zugriff, legst du einen neuen Schlüssel an. Schlüssel, die lange „noch nie verwendet“ zeigen, widerrufst du am besten.

Einen Webhook anlegen

1. Im Abschnitt Ausgehende Webhooks gibst du einen Namen und die Ziel-Adresse ein (https://…). Das ist die Adresse, an die Work7 die Meldungen schickt; sie bekommst du vom anderen Programm.
2. Hake die Ereignisse an, über die das Programm informiert werden soll. Ein Ereignisname besteht aus Bereich und Aktion, zum Beispiel site_report.completed (Regiebericht abgeschlossen), invoice.paid (Rechnung bezahlt) oder inquiry.created (Anfrage angelegt). Mit * am Ende steht ein Muster für alle Aktionen eines Bereichs, zum Beispiel inquiry.*. Angeboten werden nur Ereignisse aus Bereichen, die euer Betrieb gebucht hat. Die vollständige Liste steht unter Webhooks.
3. Webhook anlegen wird aktiv, sobald Name, Adresse und mindestens ein Ereignis gewählt sind.
4. Work7 zeigt das Webhook-Secret (whsec_…) ebenfalls nur ein einziges Mal an. Kopiere es und gib es dem Entwickler oder Dienstleister, der das andere Programm einrichtet: Damit prüft dieses Programm, dass eine Meldung wirklich von Work7 kommt.

Regeln für die Ziel-Adresse: Erlaubt sind nur öffentlich erreichbare https-Adressen. Adressen im eigenen Netz, localhost und ähnliche lehnt Work7 ab; beim Anlegen erscheint dann „Ziel-URL nicht erlaubt: …“. Die Details stehen im Abschnitt zur Ziel-URL unter Webhooks.

Was in einer Meldung steckt, sind Kennungen, Nummern, Status, Beträge und Zeitstempel, keine Beschreibungstexte und keine Dateien. Alles Weitere holt das andere Programm bei Bedarf über die Schnittstelle.

Webhooks pausieren und löschen

Jede Zeile zeigt Name, Adresse und gewählte Ereignisse.

• Pausieren hält den Webhook an, Aktivieren schaltet ihn wieder ein. Ereignisse, die während der Pause passieren, werden nicht nachgeliefert.
• Löschen entfernt den Webhook ohne Rückfrage. Willst du später dasselbe Ziel wieder anbinden, legst du ihn neu an (mit neuem Secret).

Die Ereignisse eines Webhooks kannst du hier nicht nachträglich ändern. Brauchst du andere, legst du einen neuen Webhook an und löschst den alten.

Zustellungen prüfen

Unter den Webhooks zeigt Letzte Zustellungen die jüngsten 20 Meldungen. Jede Zeile nennt Zeitpunkt, Ereignis, Status, bei Fehlern den HTTP-Code und die Fehlermeldung sowie die Zahl der Versuche. Der Status heißt:

Status	Bedeutung
wartet	Die Meldung ist noch nicht zugestellt.
fehlgeschlagen, Wiederholung geplant	Das Ziel hat nicht mit Erfolg geantwortet; Work7 versucht es später noch einmal.
zugestellt	Das Ziel hat die Meldung angenommen.
aufgegeben	Auch die letzten Versuche sind fehlgeschlagen; Work7 sendet diese Meldung nicht mehr.
abgelehnt: Ziel-URL nicht öffentlich	Die Adresse zeigt auf eine nicht öffentliche Adresse; es gibt keine Wiederholung.

Work7 versucht eine Zustellung bis zu fünf Mal mit wachsendem Abstand (siehe Wiederholungen). Bleibt eine Meldung auf „fehlgeschlagen“ oder „aufgegeben“, prüfe zuerst, ob das andere Programm erreichbar ist und die Adresse stimmt.

Tipps

• Richte zum Ausprobieren zuerst einen Schlüssel mit nur lesendem Zugriff ein und rufe mit dem Quickstart die erste Abfrage auf.
• Notiere dir, welches Programm welchen Schlüssel und welches Secret hat. So weißt du bei einem Wechsel, was zu widerrufen ist.
• Wechselt jemand im Team, der Schlüssel kannte, widerrufe die Schlüssel und lege neue an.