# API und Webhooks

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](https://docket.rocks/doku/api-leitfaden) 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.

```json
{
  "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](https://docket.rocks/doku/api-leitfaden) · [KI-Apps verbinden](https://docket.rocks/doku/ki-apps-verbinden) · [Benutzerrollen](https://docket.rocks/doku/benutzerrollen)