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