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
contact.created
contact.updated
contact.deleted

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