Een webhook aanroepen vanuit een trigger

Bijgewerkt

Opmerking: Dit artikel is technisch van aard, daarom raden wij u aan iemand met de juiste technische expertise te betrekken. Als u vragen heeft, neem contact op via support@azumuta.com.

Een webhook-trigger meldt een ander systeem zodra er iets gebeurt in Azumuta, bijvoorbeeld wanneer een productorder is voltooid of een probleem is gemeld. Gebruik dit in plaats van het poll-en van de REST API. Azumuta stuurt alleen de gegevens van dat evenement, op het moment dat het zich voordoet. Voor het bredere ERP-patroon, zie ERP Integration.

Dit artikel legt uit hoe u een Webhook aanroepen-trigger configureert: waar u deze instelt, welke velden u invult, wat Azumuta naar uw endpoint stuurt, wat er gebeurt als de oproep faalt en hoe u runs controleert en opnieuw probeert.

Een webhook-trigger toevoegen

  1. Klik op Instellingen onder Beheer.
  2. Klik op Triggers onder Integraties.
  3. Klik op Trigger toevoegen (de gele plusknop).
  4. Vul de hieronder beschreven velden in.
  5. Klik op Toevoegen wanneer u klaar bent.

Scope, What en When

Selecteer deze eerst:

  • Scope: Waar de trigger op van toepassing is, zoals alle productorders, een artikelcategorie, geselecteerde audit-werkopdrachten of een verbeterbord.
  • What: Selecteer Webhook aanroepen.
  • When: Het evenement dat de webhook aanroept, bijvoorbeeld When a product order is finished of When an audit is finished.

De evenementen per scope staan in deze artikelen:

Na aanmaak kunt u de trigger bewerken of verwijderen en de gebruiksgeschiedenis bekijken.

Attributen

Nadat u What en When heeft geselecteerd, toont de sectie Attributen de webhook-opties:

  • Endpoint: De HTTPS-URL die Azumuta zal aanroepen (het placeholder begint met https://). Dit endpoint moet toegankelijk zijn vanaf de Azumuta-servers.
  • Method: GET, POST, PUT of PATCH. Standaard is GET.
  • Payload: Wordt getoond voor elke methode behalve GET. Vul hier de aangepaste body-inhoud in. U kunt parameters in dit veld gebruiken.
  • Authentication: Hoe Azumuta zich identificeert bij uw endpoint. Zie Authentication.
  • Request timeout: Hoeveel seconden Azumuta wacht op een antwoord voordat de poging als mislukt wordt gerekend. Voer een waarde in van 1 tot 300. Laat leeg om de standaard van 30 seconden te gebruiken.
  • Retry automatically when the webhook fails: Schakel in om een mislukte oproep automatisch opnieuw te proberen. Zie Retry failed calls.

Authenticatie

Selecteer hoe Azumuta zich identificeert bij uw endpoint. Nieuwe triggers starten op Geen.

  • Geen: Azumuta stuurt geen inloggegevens.
  • Header: Azumuta stuurt één header bij elke oproep. Typ de Header name (bijvoorbeeld X-API-Key), en kies vervolgens de waarde: Custom value (een geheim dat u invoert) of API key from device (de sleutel van een Api Device). De headernamen User-Agent, Origin en Content-Type zijn gereserveerd.
  • Basic: Azumuta stuurt een gebruikersnaam en wachtwoord met HTTP Basic-authenticatie.
  • OAuth client credentials: Azumuta vraagt eerst een access token aan en stuurt dit mee met de oproep. Vul de Token URL in (dit moet een HTTPS-adres zijn), Client ID, Client secret en, indien uw provider dit vereist, Scope.

Een geheim dat u invoert (een aangepaste headervalue, een wachtwoord of een client secret) wordt veilig opgeslagen. Daarna toont het veld alleen ******, nooit de opgeslagen waarde. Het wijzigen van de webhook-URL wist het opgeslagen geheim, en bij OAuth wist ook het wijzigen van de token-URL het geheim, dus moet u dit opnieuw invoeren.

Wat Azumuta stuurt

Azumuta stuurt gebeurtenisspecifieke velden bij elke oproep:

Scope Typische velden
Product orders identifier (productordernummer), en indien van toepassing workinstructionId en recordingId
Issues issueId, issueNumber (en voor sommige evenementen gerelateerde kolom-/actievelden)
Audits recordingId, workinstructionId, en gerelateerde auditvelden zoals auditNumber

Hoe die velden worden geleverd, hangt af van de methode:

  • GET: Velden worden toegevoegd als URL query parameters.
  • POST, PUT and PATCH: Velden worden als JSON in de requestbody verzonden. Als u een aangepaste Payload heeft geconfigureerd, wordt die inhoud genest onder de sleutel payload in de JSON-body, naast de hierboven genoemde evenementvelden.

Elke oproep draagt daarnaast deze headers, zodat uw systeem de oproep kan herkennen en een herhaling kan detecteren:

Header Value
X-Azumuta-Trigger-Run-Id De ID van de trigger-run. Deze blijft hetzelfde voor elke poging van dezelfde run.
X-Azumuta-Trigger-Id De ID van de trigger.
X-Azumuta-Webhook-Attempt Het pogingnummer. De eerste oproep is 1, de eerste retry is 2, enzovoort.

Mislukte oproepen opnieuw proberen

Een oproep geldt als mislukt wanneer uw endpoint met een foutstatus antwoordt (alles behalve een 2xx-status), niet binnen de Request timeout antwoordt of niet bereikbaar is. Een mislukte oproep wordt geregistreerd als een mislukte run, dus een falende integratie verschijnt als falend in de rungeschiedenis.

Zonder retries wordt een mislukte oproep niet herhaald. Een korte storing bij uw endpoint zou dan de oproep doen verliezen. Schakel Retry automatically when the webhook fails in om dit te voorkomen:

  • Retries: Het aantal extra pogingen na de eerste, van 1 tot 10. Bij 3 retries doet Azumuta maximaal 4 oproepen. Standaard is 3.
  • Wait between retries: De tijd tussen pogingen: 15 minuten, 30 minuten, 1 uur, 2 uur, 4 uur, 8 uur of 24 uur. Standaard is 1 uur.
  • Only retry during set hours: Vink dit aan om retries te beperken tot een tijdvenster, bijvoorbeeld wanneer uw systeem 's nachts offline is. Stel de start- en eindtijd in onder Between en and, en selecteer de Timezone. Een retry die buiten het venster zou vallen, wacht tot het venster weer opent. Het venster begint standaard om 06:00 en eindigt om 22:00.

Goed om te weten:

  • Elke retry verstuurt dezelfde evenementgegevens als de eerste oproep. De retry gebruikt de trigger zoals die op dat moment is geconfigureerd, dus een nieuw endpoint of nieuwe referenties gelden voor retries die nog wachten.
  • De run wordt als Success geregistreerd zodra één poging slaagt, en als Failed zodra de laatste retry is mislukt.
  • Als u het aantal retries verlaagt terwijl een run wacht, stopt de run bij de nieuwe limiet. Als u retries uitschakelt of de trigger verwijdert, wordt de wachtende run als mislukt geregistreerd in plaats van opnieuw geprobeerd.
  • De eerste oproep wordt gedaan op het moment dat het evenement zich voordoet. Het venster geldt alleen voor retries.

Omdat een retry kan aankomen nadat een eerdere oproep uw systeem wel heeft bereikt (bijvoorbeeld wanneer uw systeem het heeft verwerkt maar het antwoord verloren ging), ontwerp uw endpoint zo dat het geen schade veroorzaakt om hetzelfde evenement twee keer te ontvangen. Gebruik de header X-Azumuta-Trigger-Run-Id om een herhaling te herkennen.

Runs controleren en opnieuw proberen

Open de gebruiksgeschiedenis van de trigger om elke run te zien. Zie See the list of triggers in your workspace and each trigger’s usage history.

Elke run heeft een van deze statussen:

Status Betekenis
Running Azumuta voert de oproep uit.
Waiting for retry De laatste poging is mislukt en een retry is gepland. De run toont welke poging de volgende is (bijvoorbeeld "Attempt 2 of 4") en wanneer, samen met de reden waarom de laatste poging faalde.
Success Het endpoint heeft geantwoord met een 2xx-status.
Failed De oproep is mislukt en er zijn geen retries meer over, of retries zijn uitgeschakeld.

Een run met meer dan één poging toont ook hoeveel pogingen er zijn gedaan.

Om de volgende poging direct uit te voeren in plaats van te wachten op het interval, klik op Retry now naast een run die Waiting for retry is.

Gebruik de REST API om runs te controleren en opnieuw te proberen

Een integratie kan de rungeschiedenis lezen en een wachtende run direct laten uitvoeren via de Azumuta REST API. De endpoints staan in de sectie Triggers van de in-app API-documentatie.

Endpoint Wat het doet
GET /api/v1/triggers/runs Toont trigger-runs, eerst de nieuwste.
GET /api/v1/triggers/runs/{triggerRunId} Geeft één run volledig terug, inclusief elke poging met de request die is verzonden en de response die is ontvangen.
POST /api/v1/triggers/runs/{triggerRunId}/retry Voert onmiddellijk de volgende poging van een wachtende run uit.

Runs opvragen. Filter de lijst met deze queryparameters:

  • triggerId: alleen runs van deze triggers.
  • status: alleen runs in deze statussen: running, retrying (de run is mislukt en wacht op de volgende poging), success of failed.
  • scope: alleen runs van triggers in deze scopes.
  • productId en issueId: alleen runs voor deze productorders of issues.
  • startedAfter en startedBefore: alleen runs gestart binnen dit tijdsinterval, als Unix-timestamps in milliseconden.
  • limit (tot 100, standaard 100) en skip: paginering van de resultaten.

Elke run in de lijst heeft een id, triggerId, scope, type, event, status, startTime, endTime, errorMessage en, voor webhooks, de endpoint en nextAttemptAt (wanneer de volgende poging gepland staat). Om de oproepen te vinden die in een periode niet zijn doorgekomen, filter op status=failed en het betreffende tijdsinterval.

Een run ophalen. De volledige run voegt attempts toe: voor elke oproep het nummer, start- en eindtijd, de request (methode, URL en body), de response (status en body) en, wanneer de oproep helemaal niet kon worden gemaakt, het errormessage. Referenties in de URL worden geredigeerd.

Een run opnieuw proberen. De run moet retrying zijn, anders wordt de oproep geweigerd. De response is de run zoals die er na de poging uitziet: success of failed als de poging dat heeft bepaald, of opnieuw retrying als de poging mislukte en een nieuwe poging werd gepland. Een geplande retry die exact op hetzelfde moment afgaat, verstuurt de request niet twee keer.

Toegang. Authenticeer zoals beschreven in Azumuta’s REST API. Als het API-scopes-experiment voor uw workspace is ingeschakeld, heeft de key de scope triggers:read nodig om runs te tonen en volledig te lezen, en de scope triggers:write om een run opnieuw te proberen. Het volledig lezen van een run en het opnieuw proberen van een run vereisen ook het recht Manage triggers, of het recht om triggers van de scope van de run te beheren, voor de gebruiker achter de oproep.

Op deze pagina