Webhooks

Mit Webhooks kann ihre Integration in Echtzeit auf Änderungen in der Platform reagieren. Webhooks können in der Developer Oberfläche registriert werden.

Transport

Webhooks werden via HTTPs an den Empfänger gesendet. Dabei ist ein gültiges HTTPs Zertifikat für die Domain notwendig! Die HTTP Methode ist POST.

Payload

Die Daten sind im Body der HTTP Anfrage als JSON Objekte gespeichert. Das Encoding ist utf-8. Das Objekt enthält Metadaten und das eigentliche Objekt welches bearbeitet wurde. Unterhalb ist ein Beispiel von so einem Payload:

{
  "id": "Webhook Event ID",
  "service": "Internes service welches die Änderung ausgelöst hat",
  "model": "Name vom Datenbankmodel, welches bearbeitet wurde",
  "event": "create | update | delete",
  "object": { ... },
  "timestamp": 1630916258.012 # UNIX Timestamp in UTC
}

Signatur

Webhooks sind mit mit SHA256 HMAC (opens new window) signiert. Damit kann die Echtheit der Webhook events überprüft werden.

Der Schlüssel mit welchem die Signatur erstellt wurde (das Webhook Secret), kann in der Detailansicht vom Webhook in der Entwickleroberfläche eingesehen werden.

Die Signatur wird als HTTP Header im feld X-Signature mitgesendet.

Überprüfen der Signatur

Zum Überprüfen der Signatur, muss der HMAC vom Inhalt der HTTP Anfrage (Content) gebildet werden. Der Inhalt der HTTP Anfrage darf dabei nicht dekodiert werden. Der Inhalt der HTTP Anfrage darf erst nach der Signaturprüfung dekodiert werden. Alle Webhook Anfragen verwenden UTF-8 encoding.

Beispieldaten:

• Test:
  • payload: test
  • webhook secret: secret-1
  • signatur: f4e0161d698df1f37ea77cc2396ea72bdbcfa5ac179f05020c3087f27f29a540
• Mit Unicode Buchstaben:
  • payload: {"ä": "ê"}
  • webhook secret: secret-1-äöê -> als UTF-8 7365637265742d312dc3a4c3b6c3aa
  • signatur: 14ad3c4c3df03867b60c6f8747e3fd5587a6bee8e60b9ae0ad36f9e217e5c85f
  • CyberChef Beispiel (opens new window)