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.
{
"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.
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:
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