> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://support.robaws.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Webhooks

Schnell navigieren:

* [Webhooks verwenden](#2-webhooks-verwenden)
* [Signatur verifizieren](#2-signatur-verifizieren)
* [Ein paar Hinweise](#2-ein-paar-hinweise)
* [Unterstützte Event-Typen](#2-unterstutzte-event-typen)

## Webhooks verwenden

Um Webhooks mit Robaws zu verwenden, registriere deinen Webhook-Endpoint per POST auf /api/v2/webhook-endpoints. Für die vollständige Request-Definition [siehe die API-Referenzdokumente](https://app.robaws.com/swagger-ui/index.html#/Webhooks/listEndpoints). Bitte speichere das Secret, das wir dir beim Erstellen des Endpoints zurückgeben, denn du brauchst es, um unsere Signaturen zu verifizieren.

Nach ein paar Sekunden, sobald dein Subscription aktiv ist, solltest du HTTP-POST-Aufrufe von uns an die URL erhalten, die du angegeben hast.

Das ist ein Beispiel für so einen HTTP-POST:

POST [https://your-host/your-webhook-endpoint](https://your-host/your-webhook-endpoint)
Content-Type: application/json
Robaws-Signature: t=1674742714,v1=signature

```json
{
    "id":"37de8552-0007-4269-a76c-06a9415c8b65",
    "event":"client.updated",
    "data": {
        ....
    }
}
```

## Signatur verifizieren

Es ist wichtig, dass du die Signatur prüfst, die wir im Header „Robaws-Signature“ mitsenden. Sonst kannst du nicht sicher sein, dass der HTTP-Call wirklich von Robaws kommt. Das ist besonders wichtig, weil wir im Event nicht nur die ID senden, sondern die vollständigen Daten.

Um unsere Signatur zu verifizieren, brauchst du das Secret, das wir dir beim Erstellen des Endpoints zurückgegeben haben.

###### Schritt 1: Timestamp und Signatur aus dem Header extrahieren

Splitte den Header mit dem Zeichen , als Trennzeichen, um eine Liste von Elementen zu erhalten. Splitte danach jedes Element mit dem Zeichen = als Trennzeichen, um ein Prefix-Value-Paar zu bekommen.
Der Wert zum Prefix t entspricht dem Timestamp, und v1 entspricht der Signatur. Alle anderen Elemente kannst du ignorieren.
Wenn du diese dann erneut auf "=" splittest, bekommst du die Werte, die du brauchst.

###### Schritt 2: Den String signed_payload vorbereiten

Der String signed_payload wird erstellt, indem du Folgendes aneinanderhängst:

Den Timestamp (als String)
Das Zeichen .
Das eigentliche JSON-Payload (also den Request-Body)

###### Schritt 3: Die erwartete Signatur bestimmen

Berechne ein HMAC mit der Hash-Funktion SHA256. Verwende das Signing-Secret des Endpoints als Key und den String signed_payload als Message. Konvertiere das Ergebnis in eine Hex-Repräsentation.

###### Schritt 4: Signaturen vergleichen

Vergleiche die Signatur aus dem Header mit der erwarteten Signatur. Wenn sie übereinstimmt, berechne die Differenz zwischen dem aktuellen Timestamp und dem empfangenen Timestamp und entscheide, ob die Differenz innerhalb deiner Toleranz liegt, um Replay-Attacken zu verhindern. Um Timing-Attacken zu vermeiden, verwende einen Constant-Time-Stringvergleich, um die erwartete Signatur mit jeder empfangenen Signatur zu vergleichen.

## Ein paar Hinweise

* Nur Admin-User können Endpoints registrieren. Aktuell gibt es keine UI, um Webhook-Endpoints zu registrieren. Das geht nur über die API.
* Wir betrachten den Webhook als erfolgreich, wenn dein Endpoint eine 2XX-Response zurückgibt. Wir versuchen mehrmals erneut zuzustellen, solange dein Endpoint nicht erfolgreich antwortet. Unser Connection-Timeout liegt bei 2 Sekunden und der Read-Timeout ebenfalls bei 2 Sekunden. Das heißt: Wenn wir innerhalb von 2 Sekunden keine Antwort bekommen, versuchen wir die Anfrage weiter zuzustellen, bis wir eine Antwort erhalten. Wenn wir nie eine erfolgreiche Antwort erhalten, können wir deinen Webhook ohne Vorwarnung pausieren.
* Webhooks kannst du einfach testen mit [https://webhook.site](https://webhook.site)

## Unterstützte Event-Typen

Aktuell werden folgende Event-Typen unterstützt. Wenn du ein weiteres Event brauchst, melde dich bitte bei uns über [support@robaws.com](mailto:support@robaws.com).

#### Kunden

client.created
client.updated

#### Ausgangsrechnungen

sales-invoice.created
sales-invoice.updated

#### Eingangsrechnungen

purchase-invoice.created
purchase-invoice.updated

#### Angebote

offer.created
offer.updated
offer.recalculated

#### Nachtragsangebote

settlement.created
settlement.updated
settlement.recalculated

#### Projekte

project.created
project.updated

#### Artikel

article.created
article.updated
article.stock-changed

#### Mitarbeiter

employee.created
employee.updated

#### Termine und Planung

planning-item.created
planning-item.updated

#### Arbeitsaufträge

work-order.created
work-order.updated

#### Betriebsmittel

material.created
material.updated

#### Anlagen-Tracking

installation.created
installation.updated

#### Dokumente & Bilder

document.created
document.updated

#### Kommentare und Chat

comment.created
comment.updated

#### Verkaufsaufträge

sales-order.created
sales-order.updated

#### Formularantworten

form-answer.created
form-answer.updated'''