Unterstützte “Event Types”

Derzeit werden die folgenden Ereignistypen unterstützt.
Wenn Sie ein anderes Ereignis benötigen, lassen Sie es uns bitte über [email protected] wissen.

Kunden

client.created

client.updated

Verkaufsrechnungen

sales-invoice.created

sales-invoice.updated

Angebote

offer.created

offer.updated

Projekte

project.created

project.updated

Artikel

article.created

article.updated

article.stock-changed

Mitarbeiter

employee.created

employee.updated

Planungselemente (Plantafel, Einsatzplanung)

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

document.created

document.updated

Aufträge

sales-order.created

sales-order.updated

Verwendung von Webhooks

Um Webhooks mit Robaws zu verwenden, registrieren Sie Ihren Webhook-Endpunkt, indem Sie einen POST an /api/v2/webhook-endpoints senden.

Für die vollständige Anfrage-Definition siehe die API-Referenzdokumentation.

Bewahren Sie das von uns zurückgegebene Secret bei der Endpointerstellung auf, da Sie es zur Verifizierung unserer Signaturen benötigen.

Nach einigen Sekunden, sobald Ihr Abonnement aktiv wird, sollten Sie HTTP-POST-Request von uns an die von Ihnen angegebene URL erhalten.


Hier ist ein Beispiel für einen solchen 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": {
        ....
    }
}

Verifizierung der Signatur

Es ist wichtig, dass Sie die Signatur, die wir im 'Robaws-Signature'-Header senden, verifizieren, da Sie sonst nicht sicherstellen können, dass der HTTP-Aufruf tatsächlich von Robaws stammt.

Dies ist besonders wichtig, da wir nicht nur die ID im Ereignis senden, sondern auch die vollständigen Daten.

Um unsere Signatur zu verifizieren, benötigen Sie das Secret, das wir Ihnen bei der Endpunkterstellung übermittelt haben.

Schritt 1: Den Zeitstempel und die Signatur aus dem Header Extrahieren

Der 'Robaws-Signature'-Header sieht etwa so aus:
t=1674742714,v1=signature

Zerlegen Sie diesen Header:

t ist der Zeitstempel.
v1 ist die Signatur.

Sie müssen den Header anhand des , Zeichens aufteilen und dann jedes Element nochmals anhand des = Zeichens aufteilen, um Zeitstempel und Signatur zu extrahieren.

Schritt 2: Erstellen der signed_payload Zeichenfolge (String)

Die signed_payload string wird durch folgende Schritte gebildet:

Nehmen Sie den Zeitstempel (als Zeichenfolge).
Fügen Sie einen Punkt (.) hinzu.
Hängen Sie den JSON-Text der Anfrage (den eigentlichen Anfragetext oder “Request Body) an.

Beispiel:
1674742714.{JSON-Daten}

Schritt 3: Berechnen der erwarteten Signatur

Jetzt müssen Sie die korrekte Signatur berechnen.

Dazu:

Verwenden Sie eine Art kryptografischen Algorithmus, den HMAC mit SHA256. (Sie können dies z.B. mit einem Online-Generator erstellen)
Nehmen Sie den Wert, den Sie im ersten Schritt erhalten haben (das Secret von Robaws), und den Inhalt der signed_payload, die Sie gerade erstellt haben.
Der Algorithmus berechnet eine neue Signatur (Hex), die Sie mit der Robaws-Signatur vergleichen können.

Schritt 4: Vergleichen Sie die Signaturen

Nehmen Sie die Signatur aus dem 'Robaws-Signature'-Header (v1) und vergleichen Sie sie mit der Signatur, die Sie gerade berechnet haben.
Um eine Übereinstimmung sicherzustellen, berechnen Sie den Unterschied zwischen dem aktuellen Zeitstempel und dem empfangenen Zeitstempel.
Entscheiden Sie, ob der Unterschied innerhalb eines akzeptablen Bereichs liegt, um sich vor Replay-Angriffen zu schützen.
Verwenden Sie für den Vergleich der Signaturen eine constant-time string comparison (Konstantzeit-Zeichenfolgenprüfung), um sich gegen Timing-Angriffe zu schützen.

Einige Überlegungen

Nur Administratoren können Webhook-Endpoints registrieren, und dies kann derzeit nur über die API erfolgen, nicht über die Benutzeroberfläche.

Wir betrachten einen Webhook als erfolgreich, wenn der Endpunkt eine 2XX-Antwort zurückgibt.

Wir werden mehrere Versuche unternehmen, solange Ihr Endpunkt keine erfolgreiche Antwort liefert.
Unser Verbindungs-Timeout beträgt 2 Sekunden und das Lese-Timeout ebenfalls 2 Sekunden. Das bedeutet, wenn wir innerhalb von 2 Sekunden keine Antwort erhalten, versuchen wir die Anfrage erneut, bis wir eine Antwort erhalten.
Wenn wir nie eine erfolgreiche Antwort erhalten, können wir Ihren Webhook ohne Vorwarnung aussetzen.

Webhooks können einfach getestet werden unter https://webhook.site.

Aktualisiert am: 21/10/2024