Was sind Webhooks?
Ein Webhook ist ein nicht-standardisierter HTTP-Request, der ausgelöst wird, wenn etwas im Ursprungssystem passiert.
Im Fall von ITscope ist dies der Fall, wenn neue Auftrags- oder Bestellantwortdokumente zur Verfügung stehen. Wenn bspw. ein Distributor A für eine Bestellung von Kunden B einen neuen Lieferschein bereitstellt, wird (wenn alles korrekt konfiguriert wurde) ein Webhook mit dieser Information an die entsprechend angegebene URL verschickt.
Struktur
Die Webhooks von ITscope sind nach folgendem Schema aufgebaut:
| eventId | ID des verschickten Webhooks |
| timestamp | Zeitstempel, wann der Webhook verschickt wurde |
| eventType | Typ des Dokuments, das den Webhook ausgelöst hat. Mögliche Werte sind ORDER, ORDERRESPONSE, DELIVERY und INVOICE |
| transactionStatus | Neuer Status der Bestellung bzw. des Auftrags (bspw. ARRIVED oder PROCESSING) |
| orderId | ID der Bestellung bzw. des Auftrags |
| itscopeOrderId | von ITscope vergebene ID der Bestellung bzw. des Auftrags |
| documentId | ID des Dokuments, das den Webhook ausgelöst hat |
| documentUrl | URL, um via ITscope API auf das eigentliche Dokument zugreifen zu können |
| transactionId | ID der Transaktion |
Ein Webhook für einen neuen Lieferschein könnte bspw. folgendermaßen aussehen:
{
"eventId": "e2a6a466-3b62-4bb7-af53-b59aec592b49",
"timestamp": "2023-10-17T11:01:36",
"eventType": "DELIVERY",
"transactionStatus": "ADVISED",
"orderId": "123-SAMPLE-456",
"itscopeOrderId": "SAMPLE-123456-789",
"documentId": "123456789",
"documentUrl": "https://api.itscope.com/2.1/business/documents/123456789-1234-5678-9123-12SAMPLE4567/DISPATCHNOTIFICATION.xml",
"transactionId": "123456789-1234-5678-9123-12SAMPLE4567"
}Einrichtung
Die Webhook-Einstellungen sind in der Kopfleiste über dem Profilbild rechts > Mein Account > Tabreiter Webhooks erreichbar. Diese Seite ist für alle Nutzer sichtbar. Änderungen können nur vorgenommen werden, wenn der ausführende Nutzer ein Firmenadmin ist und wenn im Vertrag der Firma die notwendigen Module erworben sind. Diese sind für Altverträge „Business API“ und für Neuverträge entweder „Individuelle API-Integration“ oder „Standard-Integration„.
Die Einstellungen unterteilen sich in grob in zwei Bereichen:
- In „Basisauthentifizierung“ können die Zugangsdaten zum Zielsystem eingetragen werden, damit die Webhooks mit diesen verschickt werden, sollte der Server der eingetragenen URLs eine derartige Authentifizierung erwarten. Wenn bereits ein Passwort hinterlegt ist, wird dies über einen Hinweis bei dem Eingabefeld angezeigt. Das eigentliche Passwort wird in der Oberfläche nicht angezeigt. Sollte das Passwort-Feld leer gelassen werden, wird diese Information beim Speichern nicht übertragen und das alte Passwort bleibt bestehen.
- Unter URLs können die Links eingetragen werden, zu dem die jeweiligen Webhooks versendet werden sollen. Dafür muss die jeweilige Checkbox ausgewählt und eine https-URL eingetragen werden. Erst wenn beides erfüllt ist, werden die Webhooks auch verschickt. Über den „Testen“-Button kann ein Dummy-Webhook zu der eingetragenen URL versendet werden.
Die Webhook-Einstellungen werden erst gespeichert, wenn der Button „Änderungen übernehmen“ geklickt worden ist.