Einen Webhook von einem Trigger aufrufen

Aktualisiert

Hinweis: Dieser Artikel ist technisch; wir empfehlen, jemanden mit entsprechendem technischem Fachwissen hinzuzuziehen. Bei Fragen kontaktieren Sie uns unter support@azumuta.com.

Ein webhook trigger benachrichtigt ein anderes System, sobald in Azumuta etwas passiert, z. B. wenn ein Produktauftrag abgeschlossen oder ein Problem gemeldet wird. Verwenden Sie ihn anstelle des wiederholten Abfragens der REST API. Azumuta sendet nur die Daten dieses Ereignisses zum Zeitpunkt des Eintretens. Für das umfassendere ERP-Muster siehe ERP Integration.

Dieser Artikel erklärt, wie Sie einen Trigger vom Typ Call a webhook konfigurieren: wo Sie ihn einrichten, welche Attribute auszufüllen sind, was Azumuta an Ihren Endpunkt sendet, was passiert, wenn der Aufruf fehlschlägt, und wie Sie Runs prüfen und erneut ausführen.

Webhook-Trigger hinzufügen

  1. Klicken Sie auf Settings unter Management.
  2. Klicken Sie auf Triggers unter Integrations.
  3. Klicken Sie auf Add trigger (die gelbe Plus-Schaltfläche).
  4. Füllen Sie die unten beschriebenen Felder aus.
  5. Wenn Sie fertig sind, klicken Sie auf Add.

Scope, What and When

Wählen Sie zunächst Folgendes aus:

  • Scope: Worauf der Trigger angewendet wird, z. B. alle Produktaufträge, eine Artikelkategorie, ausgewählte Audit-Arbeitsanweisungen oder ein Improvement Board.
  • What: Wählen Sie Call a webhook.
  • When: Das Ereignis, das den Webhook aufruft, z. B. When a product order is finished oder When an audit is finished.

Die Ereignisse pro Scope sind in diesen Artikeln aufgeführt:

Nach der Erstellung können Sie den Trigger edit or delete und die usage history einsehen.

Attributes

Nachdem Sie What und When ausgewählt haben, zeigt der Abschnitt Attributes die Webhook-Optionen an:

  • Endpoint: Die HTTPS-URL, die Azumuta aufruft (Platzhalter beginnt mit https://). Dieser Endpunkt muss von den Azumuta-Servern erreichbar sein.
  • Method: GET, POST, PUT oder PATCH. Standard ist GET.
  • Payload: Wird für alle Methoden außer GET angezeigt. Geben Sie hier den benutzerdefinierten Body-Inhalt ein. Sie können Parameter in diesem Feld verwenden.
  • Authentication: Wie Azumuta sich bei Ihrem Endpunkt identifiziert. Siehe Authentication.
  • Request timeout: Wie viele Sekunden Azumuta auf eine Antwort wartet, bevor der Versuch als fehlgeschlagen gilt. Geben Sie einen Wert von 1 bis 300 ein. Lassen Sie das Feld leer, um den Standard von 30 Sekunden zu verwenden.
  • Retry automatically when the webhook fails: Einschalten, um einen fehlgeschlagenen Aufruf erneut zu versuchen. Siehe Retry failed calls.

Authentication

Wählen Sie, wie Azumuta sich gegenüber Ihrem Endpunkt authentifiziert. Neue Trigger beginnen mit None.

  • None: Azumuta sendet keine Anmeldeinformationen.
  • Header: Azumuta sendet bei jedem Aufruf einen Header. Geben Sie den Header name ein (z. B. X-API-Key), und wählen Sie dann den Wert: Custom value (ein von Ihnen eingegebenes Secret) oder API key from device (der Schlüssel eines Api Device). Die Header-Namen User-Agent, Origin und Content-Type sind reserviert.
  • Basic: Azumuta sendet einen Benutzernamen und ein Passwort mittels HTTP Basic-Authentifizierung.
  • OAuth client credentials: Azumuta fordert zuerst ein Access-Token an und sendet es mit dem Aufruf. Füllen Sie Token URL (muss eine HTTPS-Adresse sein), Client ID, Client secret und, falls Ihr Provider eines benötigt, Scope aus.

Ein von Ihnen eingegebenes Secret (ein benutzerdefinierter Header-Wert, ein Passwort oder ein Client-Secret) wird sicher gespeichert. Danach zeigt das Feld nur noch ****** an, niemals den gespeicherten Wert. Das Ändern der Webhook-URL löscht das gespeicherte Secret, und bei OAuth löscht auch das Ändern der Token-URL das Secret, sodass Sie es erneut eingeben müssen.

Was Azumuta sendet

Azumuta sendet ereignisspezifische Felder bei jedem Aufruf:

Scope Typische Felder
Product orders identifier (Produktauftragsnummer), und, wenn zutreffend, workinstructionId und recordingId
Issues issueId, issueNumber (und bei einigen Ereignissen verwandte Spalten-/Aktionfelder)
Audits recordingId, workinstructionId und zugehörige Audit-Felder wie auditNumber

Wie diese Felder übermittelt werden, hängt von der Methode ab:

  • GET: Felder werden als URL-Query-Parameter hinzugefügt.
  • POST, PUT and PATCH: Felder werden als JSON im Request-Body gesendet. Wenn Sie eine benutzerdefinierte Payload konfiguriert haben, wird dieser Inhalt im JSON-Body neben den oben genannten Ereignisfeldern unter dem Schlüssel payload verschachtelt.

Jeder Aufruf enthält außerdem diese Header, damit Ihr System den Aufruf erkennen und Wiederholungen identifizieren kann:

Header Value
X-Azumuta-Trigger-Run-Id Die ID des Trigger-Runs. Sie bleibt bei jedem Versuch desselben Runs gleich.
X-Azumuta-Trigger-Id Die ID des Triggers.
X-Azumuta-Webhook-Attempt Die Versuchsnummer. Der erste Aufruf ist 1, der erste Retry ist 2 usw.

Fehlgeschlagene Aufrufe erneut versuchen

Ein Aufruf gilt als failed, wenn Ihr Endpunkt mit einem Fehlerstatus antwortet (alles außer einem 2xx-Status), innerhalb des Request timeout nicht antwortet oder nicht erreichbar ist. Ein fehlgeschlagener Aufruf wird als fehlgeschlagener Run protokolliert, sodass eine fehlerhafte Integration in der Run-Historie als fehlerhaft angezeigt wird.

Ohne Retries wird ein fehlgeschlagener Aufruf nicht wiederholt. Eine kurze Störung bei Ihrem Endpunkt würde den Aufruf dann verlieren. Schalten Sie Retry automatically when the webhook fails ein, um ihn zu wiederholen:

  • Retries: Die Anzahl zusätzlicher Versuche nach dem ersten, von 1 bis 10. Bei 3 Retries führt Azumuta bis zu 4 Aufrufe aus. Standard ist 3.
  • Wait between retries: Die Zeit zwischen den Versuchen: 15 Minuten, 30 Minuten, 1 Stunde, 2 Stunden, 4 Stunden, 8 Stunden oder 24 Stunden. Standard ist 1 Stunde.
  • Only retry during set hours: Aktivieren Sie dies, um Retries auf ein Zeitfenster zu beschränken, z. B. wenn Ihr System nachts offline ist. Legen Sie Start- und Endzeit unter Between und and fest und wählen Sie die Timezone. Ein Retry, der außerhalb des Fensters liegen würde, wartet, bis das Fenster wieder geöffnet ist. Standardmäßig beginnt das Fenster um 06:00 und endet um 22:00.

Gut zu wissen:

  • Jeder Retry sendet dieselben Ereignisdaten wie der erste Aufruf. Der Retry verwendet den Trigger in der zu diesem Zeitpunkt aktuellen Konfiguration, sodass ein neuer Endpunkt oder neue Zugangsdaten für noch ausstehende Retries gelten.
  • Der Run wird als Success aufgezeichnet, sobald ein Versuch erfolgreich ist, und als Failed, sobald der letzte Retry fehlgeschlagen ist.
  • Wenn Sie die Anzahl der Retries verringern, während ein Run wartet, stoppt der Run bei der neuen Grenze. Wenn Sie Retries ausschalten oder den Trigger löschen, wird der wartende Run als failed aufgezeichnet, anstatt erneut versucht zu werden.
  • Der erste Aufruf erfolgt zum Zeitpunkt des Ereignisses. Das Zeitfenster gilt nur für Retries.

Da ein Retry nach einem Aufruf eintreffen kann, der Ihr System erreicht hat (z. B. wenn Ihr System den Aufruf verarbeitet hat, die Antwort aber verloren ging), sollten Sie Ihren Endpunkt so gestalten, dass das mehrfache Empfangen desselben Ereignisses keinen Schaden anrichtet. Verwenden Sie den Header X-Azumuta-Trigger-Run-Id, um eine Wiederholung zu erkennen.

Runs prüfen und erneut ausführen

Öffnen Sie die Nutzungsverlauf des Triggers, um alle Runs zu sehen. Siehe See the list of triggers in your workspace and each trigger’s usage history.

Jeder Run hat einen dieser Status:

Status Bedeutung
Running Azumuta führt den Aufruf aus.
Waiting for retry Der letzte Versuch ist fehlgeschlagen und ein Retry ist geplant. Der Run zeigt, welcher Versuch als nächstes ansteht (z. B. "Versuch 2 von 4") und wann, zusammen mit dem Grund, warum der letzte Versuch fehlgeschlagen ist.
Success Der Endpunkt hat mit einem 2xx-Status geantwortet.
Failed Der Aufruf ist fehlgeschlagen und es sind keine Retries mehr übrig, oder Retries sind deaktiviert.

Ein Run mit mehr als einem Versuch zeigt außerdem, wie viele Versuche durchgeführt wurden.

Um den nächsten Versuch sofort auszuführen, anstatt auf das Intervall zu warten, klicken Sie neben einem Run im Status Waiting for retry auf Retry now.

Verwenden Sie die REST API, um Runs zu prüfen und erneut auszuführen

Eine Integration kann die Run-Historie lesen und einen wartenden Run über sich selbst weiterleiten mit der Azumuta REST API. Die Endpunkte finden Sie im Triggers-Abschnitt der In-App-API-Dokumentation.

Endpoint What it does
GET /api/v1/triggers/runs Lists trigger runs, newest first.
GET /api/v1/triggers/runs/{triggerRunId} Returns one run in full, including every attempt with the request it sent and the response it got back.
POST /api/v1/triggers/runs/{triggerRunId}/retry Runs the next attempt of a waiting run immediately.

List runs. Filtern Sie die Liste mit diesen Query-Parametern:

  • triggerId: nur Runs dieser Trigger.
  • status: nur Runs in diesen Status: running, retrying (der Run ist fehlgeschlagen und wartet auf den nächsten Versuch), success oder failed.
  • scope: nur Runs von Triggern in diesen Scopes.
  • productId und issueId: nur Runs für diese Produktaufträge oder Issues.
  • startedAfter und startedBefore: nur Runs, die in diesem Zeitraum gestartet wurden, als Unix-Timestamps in Millisekunden.
  • limit (bis zu 100, Standard 100) und skip: blättern Sie durch die Ergebnisse.

Jeder Run in der Liste hat eine id, triggerId, scope, type, event, status, startTime, endTime, errorMessage und für Webhooks die Felder endpoint und nextAttemptAt (wann der nächste Versuch geplant ist). Um die Aufrufe zu finden, die in einem Zeitraum nicht durchgekommen sind, filtern Sie auf status=failed und den Zeitraum.

Retrieve a run. Der vollständige Run enthält attempts: für jeden Aufruf seine Nummer, Start- und Endzeit, die Request (Methode, URL und Body), die Response (Status und Body) und, wenn der Aufruf gar nicht durchgeführt werden konnte, die Fehlermeldung. Zugangsdaten in der URL werden redigiert.

Retry a run. Der Run muss retrying sein, sonst wird der Aufruf abgelehnt. Die Response ist der Run in dem Zustand, in dem er nach dem Versuch steht: success oder failed, falls der Versuch ihn abschließt, oder wieder retrying, wenn er fehlgeschlagen ist und ein weiterer Versuch geplant wurde. Ein geplanter Retry, der zum selben Zeitpunkt ausgelöst wird, sendet die Anfrage nicht zweimal.

Access. Authentifizieren Sie sich wie in Azumuta’s REST API beschrieben. Wenn das API-Scopes-Experiment für Ihren Workspace aktiviert ist, benötigt der Key die Scope triggers:read, um Runs aufzulisten und vollständig zu lesen, und die Scope triggers:write, um einen Run erneut auszuführen. Das vollständige Lesen eines Runs und das erneute Ausführen eines Runs erfordern außerdem das Recht Manage triggers oder das Recht, Trigger im Scope des Runs zu verwalten, für den Benutzer, der die Anfrage ausführt.

Auf dieser Seite