API und Webhooks

docket mit n8n, Make, Zapier oder eigenen Skripten verbinden: persönliche API-Schlüssel für die GraphQL-API und Webhooks, die euren Tools sagen, wenn etwas passiert.

Zwei Dinge verbinden docket mit den Tools drumherum. Über die API liest und schreibt ein Skript oder ein Automatisierungstool, was eine Person in der App kann. Webhooks sagen einer Adresse von euch Bescheid, wenn etwas passiert ist, damit niemand immer wieder nachfragen muss.

Die API einschalten

Ein Admin schaltet sie unter Administration → Integrationen → API ein. Vorher kann niemand einen Schlüssel anlegen, und kein Schlüssel funktioniert.

API-Schlüssel

Jede Person legt ihre eigenen Schlüssel in ihren Profileinstellungen an, unter API-Schlüssel. Ein Schlüssel handelt als die Person, die ihn angelegt hat, mit genau ihrer Rolle: Der Schlüssel eines Zeiterfassers sieht seine Projekte und seine Zeit, der eines Admins sieht die Zahlen.

Zum Anlegen fragt docket nach deinem Passwort.
Der Schlüssel wird einmal angezeigt, beim Anlegen. docket behält nur einen Fingerabdruck davon. Ein verlorener Schlüssel wird ersetzt, nicht wiederhergestellt.
Ein Schlüssel läuft nach 90 Tagen ab, außer du wählst 30 Tage, ein Jahr oder Nie.
Ein Schlüssel gilt nicht mehr, sobald du ihn entfernst oder der Admin die API ausschaltet.
Ein Schlüssel wird gelöscht, wenn die Person ihr Passwort ändert, archiviert wird oder ein Admin alle abmeldet. Automationen, die ihn nutzen, stehen dann still, bis du einen neuen anlegst; das Abmelden aus docket lässt Schlüssel in Ruhe.
Was nur eine angemeldete Person tut, bleibt Schlüsseln verschlossen: die Einstellungen des Workspace, Nutzer, die Verbindungen zu Jira und KI-Apps und die Schlüssel und Webhooks selbst.
Ein Schlüssel darf 120 Anfragen pro Minute senden.

Die API aufrufen

Die API von docket ist GraphQL, dieselbe, die die App benutzt. Sie liegt unter der Adresse eures Workspace:

POST https://euerworkspace.docket.rocks/graphql
Authorization: Bearer dkt_…
Content-Type: application/json

{ "query": "{ viewer { id } }" }

Das Schema mit allen Abfragen und Mutationen und einer Beschreibung an jeder liegt unter /graphql/schema (mit demselben Header). Die Ids in Webhook-Ereignissen sind die Ids, die die API nimmt. Der API-Leitfaden für Entwickler geht die üblichen Aufrufe durch.

Die API ist die der App und wächst mit ihr. Ein Feld, das wegfällt, ist vorher im Schema als veraltet markiert.

Webhooks

Ein Admin legt einen Webhook unter Administration → Integrationen → API an: eine https-Adresse und die Ereignisse, von denen sie erfahren soll. Ein Webhook-Node in n8n, ein Custom webhook in Make oder ein Catch Hook in Zapier gibt euch so eine Adresse.

Ereignis	Wann
`project.created`	ein Projekt wird angelegt
`ticket.created`, `ticket.closed`, `ticket.reopened`	ein Ticket wird angelegt, geschlossen oder wieder geöffnet (nicht beim Anlegen von Tickets, die aus Jira gespiegelt sind)
`time_entry.created`	Zeit wird gebucht (nicht bei Worklogs, die aus Jira übernommen werden)
`quotation.published`, `quotation.confirmed`, `quotation.canceled`	ein Angebot geht raus, wird bestätigt oder storniert
`order_confirmation.published`, `delivery_note.published`	das Dokument geht raus
`invoice.published`, `invoice.paid`, `invoice.payment_reversed`, `invoice.canceled`	eine Rechnung geht raus, wird als bezahlt markiert, die Zahlung wird zurückgenommen oder sie wird storniert

Jedes Ereignis ist ein kleines JSON-Dokument: was passiert ist, wann, in welchem Workspace, wer es getan hat, dazu die Id des Datensatzes und ein paar Fakten. Eine Rechnung bringt Nummer, Daten, Netto und Brutto mit.

{
  "id": "6c1f…",
  "event": "invoice.paid",
  "created_at": "2026-11-12T09:30:00Z",
  "workspace": "euerworkspace",
  "actor": { "id": "…", "name": "Ada Lovelace" },
  "data": { "type": "invoice", "id": "…", "number": "20042", "status": "paid", "net": 4230.0, "gross": 5033.7, "currency": "EUR" }
}

Prüfen, dass es docket ist

Jede Zustellung ist mit dem Geheimnis des Webhooks signiert, das in seiner Zeile steht:

X-Docket-Signature: t=1794475800,v1=5f3a…

v1 ist der HMAC-SHA256 von <t>.<body> mit dem Geheimnis. Rechnet ihn selbst und vergleicht; lehnt Zustellungen ab, deren t alt ist. X-Docket-Delivery bleibt bei einer Wiederholung gleich, so lassen sich Doppelte verwerfen.

Wenn eure Adresse nicht antwortet

Jede Antwort mit einem 200er-Code zählt als angekommen. Sonst versucht docket es noch einmal, fünfmal innerhalb von etwa einer Stunde, und gibt die Zustellung dann auf. Nach zwanzig Zustellungen in Folge, die nicht ankamen, schaltet docket den Webhook aus; ein Admin schaltet ihn wieder ein. In der Zeile des Webhooks stehen seine letzten Zustellungen mit der jeweiligen Antwort, zwei Wochen lang.

docket stellt nur an https-Adressen im öffentlichen Internet zu.

Verwandt: API-Leitfaden für Entwickler · KI-Apps verbinden · Benutzerrollen