Webhooks
Schnell navigieren:
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. 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
Content-Type: application/json
Robaws-Signature: t=1674742714,v1=signature
{
"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
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.
Kunden
client.created
client.updated
Ausgangsrechnungen
sales-invoice.created
sales-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'''
Aktualisiert am: 05/01/2026
Danke!