Webhooks einrichten

Last modified: 19. Oktober 2023

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:

eventIdID des verschickten Webhooks
timestampZeitstempel, wann der Webhook verschickt wurde
eventTypeTyp des Dokuments, das den Webhook ausgelöst hat. Mögliche Werte sind ORDER, ORDERRESPONSE, DELIVERY und INVOICE
transactionStatusNeuer Status der Bestellung bzw. des Auftrags (bspw. ARRIVED oder PROCESSING)
orderIdID der Bestellung bzw. des Auftrags
itscopeOrderIdvon ITscope vergebene ID der Bestellung bzw. des Auftrags
documentIdID des Dokuments, das den Webhook ausgelöst hat
documentUrlURL, um via ITscope API auf das eigentliche Dokument zugreifen zu können
transactionIdID der Transaktion
Struktur von ITscope Webhooks

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:

  1. 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.
  2. 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.

Was this article helpful?
Dislike 0
Views: 249