Webhooks

Mit Webhooks können externe Anwendungen über Ereignisse in asello informiert werden. Die vorhandenen Ereignisse werden in Folge beschrieben:

Events

Aktuell sind die folgenden Events / Aktionen mit den Webhooks verfügbar:

document created
document updated
receipt created
receipt updated
invoice created
invoice updated
deliverynote created
deliverynote updated
order created
order updated
deliveryorder created
deliveryorder updated

Die Webhooks sind in asello konfigurierbar. Dafür sind die folgenden Parameter notwendig:

description
action / event
uri
secret
paused

Implementierung

Um die Webhooks verwenden zu können, müssen Sie einen http-Rest-Service zur Verfügung stellen, welcher im Internet verfügbar ist und eine Rest-Route implementiert hat (z.B. https://example.com/webhook). Die Route muss die GET und POST Methoden unterstützen.

Get Methode

Die GET Methode überprüft die Operationen des remote-Servers. Eine echo-requests wird an die Webhook URL gesendet. Die Antwort muss die echo Parameter als Inhalt zur Verfügung stellen und diese als "text/plain" zurückgeben.

Request

GET https://example.com/webhook?echo=4acbe33406244d109888260d2c61b844

Response

Content-Type: text/plain

4acbe33406244d109888260d2c61b844

Post Methode

Die POST Methode wird immer dann aufgerufen, wenn der Webhook ausgelöst wird. Der Request sollte so schnell wie möglich abgeschickt werden. Es wird empfohlen eine message-queue zu verwenden, um eingehende Nachrichten des Webhooks zu speichern und diese mit einem Prozess zu verarbeiten.

Request

GET https://example.com/webhook

signature:sha256=3E556EFE80B970D65449A076D52698DF028CCFD2F7361B25E3EA948661040560 request-id:"|4ec68e80deb0ed459e52320821cc4d63.b25b135c_b25b135d_21.

JS

{
  "id": "642f2a88afc54fb5b3dc5e93a48dad6a",
  "attempt": 1,
  "properties": {},
  "notifications": [
    {
      "action": "document.created",
      "id": 9420657
    }
  ]
}

Signierte Nachricht

Die Nachricht ist mit einem Hmac Sha256 signiert. Die Signatur und der Hashing Algorithmus werden im "signature" header gespeichert.

CODE

signature:sha256=3E556EFE80B970D65449A076D52698DF028CCFD2F7361B25E3EA948661040560

Um die Signatur zu validieren, muss der Hmac des Nachrichtenbodys berechnet werden und das Ergebnis in Hexadezimal formatiert werden.

Node.js Beispiel:

JS

var secret = "test-example-secret-with-minimum-length-32-chars";
var calculatedHash = crypto.createHmac('sha256', secret).update(req.body).digest('hex');

if(hash.toLocaleLowerCase() != calculatedHash.toLocaleLowerCase()) {
    console.log("hash error");
}

Beispiel

Einen beispielhaften Server finden Sie in der node.js Datei auf der GitHub Seite der asello Webhooks: https://github.com/asello/asello-webhooks