Appeler un webhook depuis un déclencheur

Mis à jour

Remarque : Cet article est technique ; nous vous recommandons d'y associer une personne disposant des compétences techniques appropriées. Si vous avez des questions, contactez-nous à support@azumuta.com.

Un webhook trigger informe immédiatement un autre système lorsqu’un événement se produit dans Azumuta, par exemple lorsqu’une commande produit est terminée ou qu’un problème est signalé. Utilisez-le plutôt que de sonder le REST API. Azumuta n’envoie que les données de cet événement, au moment où il se produit. Pour le schéma d’intégration ERP plus large, voyez ERP Integration.

Cet article explique comment configurer un déclencheur Call a webhook : où le paramétrer, quels attributs remplir, ce qu’Azumuta envoie à votre endpoint, ce qui se passe en cas d’échec de l’appel, et comment consulter et relancer les exécutions.

Add a webhook trigger

  1. Cliquez sur Settings sous Management.
  2. Cliquez sur Triggers sous Integrations.
  3. Cliquez sur Add trigger (le bouton jaune plus).
  4. Remplissez les champs décrits ci-dessous.
  5. Lorsque vous avez terminé, cliquez sur Add.

Scope, What and When

Sélectionnez d’abord :

  • Scope : À quoi s’applique le déclencheur, par exemple toutes les commandes produit, une catégorie d’article, des instructions de travail d’audit sélectionnées ou un tableau d’amélioration.
  • What : Sélectionnez Call a webhook.
  • When : L’événement qui déclenche le webhook, par exemple When a product order is finished ou When an audit is finished.

Les événements par scope sont listés dans ces articles :

Après la création, vous pouvez edit or delete le déclencheur, et consulter l’usage history.

Attributes

Après avoir sélectionné What et When, la section Attributes affiche les options du webhook :

  • Endpoint : L’URL HTTPS que Azumuta appellera (le placeholder commence par https://). Cet endpoint doit être accessible depuis les serveurs Azumuta.
  • Method : GET, POST, PUT ou PATCH. La valeur par défaut est GET.
  • Payload : Affiché pour toutes les méthodes sauf GET. Saisissez ici le contenu personnalisé du corps. Vous pouvez utiliser des paramètres dans ce champ.
  • Authentication : Comment Azumuta s’identifie auprès de votre endpoint. Voir Authentication.
  • Request timeout : Le nombre de secondes pendant lesquelles Azumuta attend une réponse avant que la tentative ne soit considérée comme échouée. Saisissez une valeur de 1 à 300. Laissez vide pour utiliser la valeur par défaut de 30 secondes.
  • Retry automatically when the webhook fails : Activez pour retenter un appel échoué. Voir Retry failed calls.

Authentication

Sélectionnez la façon dont Azumuta s’identifie auprès de votre endpoint. Les nouveaux déclencheurs démarrent sur None.

  • None : Azumuta n’envoie aucune information d’identification.
  • Header : Azumuta envoie un en-tête avec chaque appel. Tapez le Header name (par exemple X-API-Key), puis choisissez la valeur : Custom value (un secret que vous saisissez) ou API key from device (la clé d’un Api Device). Les noms d’en-tête User-Agent, Origin et Content-Type sont réservés.
  • Basic : Azumuta envoie un nom d’utilisateur et un mot de passe en utilisant l’authentification HTTP Basic.
  • OAuth client credentials : Azumuta demande d’abord un jeton d’accès puis l’envoie avec l’appel. Renseignez le Token URL (doit être une adresse HTTPS), le Client ID, le Client secret et, si votre fournisseur en a besoin, le Scope.

Un secret que vous saisissez (valeur d’en-tête personnalisée, mot de passe ou client secret) est enregistré de manière sécurisée. Ensuite, le champ n’affiche que ******, jamais la valeur enregistrée. La modification de l’URL du webhook efface le secret enregistré, et pour OAuth, la modification du Token URL effectue la même opération, vous obligeant à le ressaisir.

What Azumuta sends

Azumuta envoie des champs spécifiques à l’événement avec chaque appel :

Scope Typical fields
Product orders identifier (numéro de commande produit), et le cas échéant workinstructionId et recordingId
Issues issueId, issueNumber (et pour certains événements, des champs liés à la colonne/action)
Audits recordingId, workinstructionId, et des champs d’audit associés tels que auditNumber

La manière dont ces champs sont livrés dépend de la méthode :

  • GET : Les champs sont ajoutés en tant que paramètres de requête URL.
  • POST, PUT and PATCH : Les champs sont envoyés en JSON dans le corps de la requête. Si vous avez configuré un Payload personnalisé, ce contenu est imbriqué sous la clé payload dans le corps JSON, à côté des champs d’événement ci‑dessus.

Chaque appel contient également ces en‑têtes, afin que votre système puisse reconnaître l’appel et détecter une répétition :

Header Value
X-Azumuta-Trigger-Run-Id L’ID de l’exécution du déclencheur. Il reste identique pour chaque tentative de la même exécution.
X-Azumuta-Trigger-Id L’ID du déclencheur.
X-Azumuta-Webhook-Attempt Le numéro de tentative. Le premier appel est 1, la première réessai est 2, etc.

Retry failed calls

Un appel est considéré comme échoué lorsque votre endpoint répond avec un statut d’erreur (tout statut autre que 2xx), ne répond pas dans le délai défini par Request timeout, ou est injoignable. Un appel échoué est enregistré comme une exécution échouée, donc une intégration défaillante apparaît comme telle dans l’historique des exécutions.

Sans réessais, un appel échoué n’est pas répété. Une courte indisponibilité de votre endpoint ferait alors perdre l’appel. Activez Retry automatically when the webhook fails pour le répéter :

  • Retries : Le nombre de tentatives supplémentaires après la première, de 1 à 10. Avec 3 réessais, Azumuta effectue jusqu’à 4 appels. La valeur par défaut est 3.
  • Wait between retries : Le temps entre les tentatives : 15 minutes, 30 minutes, 1 heure, 2 heures, 4 heures, 8 heures ou 24 heures. La valeur par défaut est 1 heure.
  • Only retry during set hours : Cochez pour limiter les réessais à une plage horaire, par exemple si votre système est hors ligne la nuit. Définissez l’heure de début et de fin sous Between et and, puis sélectionnez le Timezone. Un réessai qui tomberait en dehors de la plage attend jusqu’à la réouverture de la fenêtre. La fenêtre commence par défaut à 06:00 et se termine à 22:00.

Bon à savoir :

  • Chaque réessai envoie les mêmes données d’événement que le premier appel. Le réessai utilise le déclencheur tel qu’il est configuré au moment du réessai, donc un nouvel endpoint ou de nouvelles informations d’identification s’appliquent aux réessais encore en attente.
  • L’exécution est enregistrée comme Success dès qu’une tentative réussit, et comme Failed une fois que le dernier réessai a échoué.
  • Si vous réduisez le nombre de réessais pendant qu’une exécution est en attente, l’exécution s’arrête à la nouvelle limite. Si vous désactivez les réessais ou supprimez le déclencheur, l’exécution en attente est enregistrée comme échouée au lieu d’être réessayée.
  • Le premier appel est effectué au moment où l’événement se produit. La fenêtre ne s’applique qu’aux réessais.

Comme un réessai peut arriver après un appel qui a bien atteint votre système (par exemple si votre système l’a traité mais que la réponse a été perdue), concevez votre endpoint pour que la réception du même événement deux fois n’ait pas d’effets indésirables. Utilisez l’en‑tête X-Azumuta-Trigger-Run-Id pour reconnaître une répétition.

Check and retry runs

Ouvrez l’historique d’utilisation du déclencheur pour voir chaque exécution. Voir See the list of triggers in your workspace and each trigger’s usage history.

Chaque exécution a l’un des statuts suivants :

Status Meaning
Running Azumuta est en train d’effectuer l’appel.
Waiting for retry La dernière tentative a échoué et un réessai est planifié. L’exécution indique quelle tentative est la suivante (par exemple "Attempt 2 of 4") et quand, ainsi que la raison de l’échec de la dernière tentative.
Success L’endpoint a répondu avec un statut 2xx.
Failed L’appel a échoué et il ne reste plus de réessais, ou les réessais sont désactivés.

Une exécution comportant plusieurs tentatives affiche également le nombre total de tentatives effectuées.

Pour lancer la tentative suivante immédiatement au lieu d’attendre l’intervalle, cliquez sur Retry now à côté d’une exécution qui est Waiting for retry.

Use the REST API to check and retry runs

Une intégration peut lire l’historique des exécutions et relancer une exécution en attente via le Azumuta REST API. Les endpoints se trouvent dans la section Triggers de la documentation API intégrée.

Endpoint What it does
GET /api/v1/triggers/runs Liste les exécutions des déclencheurs, les plus récentes en premier.
GET /api/v1/triggers/runs/{triggerRunId} Retourne une exécution complète, y compris chaque tentative avec la requête envoyée et la réponse reçue.
POST /api/v1/triggers/runs/{triggerRunId}/retry Lance immédiatement la tentative suivante d’une exécution en attente.

List runs. Filtrez la liste avec ces paramètres de requête :

  • triggerId : uniquement les exécutions de ces déclencheurs.
  • status : uniquement les exécutions dans ces statuts : running, retrying (l’exécution a échoué et attend la tentative suivante), success ou failed.
  • scope : uniquement les exécutions des déclencheurs dans ces scopes.
  • productId et issueId : uniquement les exécutions pour ces commandes produit ou problèmes.
  • startedAfter et startedBefore : uniquement les exécutions démarrées dans cette période, en timestamps Unix en millisecondes.
  • limit (jusqu’à 100, par défaut 100) et skip : pagination des résultats.

Chaque exécution dans la liste a un id, triggerId, scope, type, event, status, startTime, endTime, errorMessage et, pour les webhooks, endpoint et nextAttemptAt (quand la prochaine tentative est prévue). Pour trouver les appels qui n’ont pas été reçus sur une période, filtrez sur status=failed et sur la période.

Retrieve a run. L’exécution complète ajoute attempts : pour chaque appel son numéro, l’heure de début et de fin, la requête (méthode, URL et corps), la réponse (statut et corps) et, lorsque l’appel n’a pas pu être effectué du tout, le message d’erreur. Les identifiants dans l’URL sont masqués.

Retry a run. L’exécution doit être retrying, sinon l’appel est refusé. La réponse est l’exécution telle qu’elle se présente après la tentative : success ou failed si la tentative l’a réglée, ou retrying à nouveau si elle a échoué et qu’une autre tentative a été planifiée. Un réessai planifié qui se déclenche au même moment n’envoie pas la requête deux fois.

Accès. Authentifiez-vous comme décrit dans Azumuta’s REST API. Si l’expérience des scopes API est activée pour votre workspace, la clé a besoin du scope triggers:read pour lister les exécutions et les lire en entier, et du scope triggers:write pour relancer une exécution. La lecture complète d’une exécution et la relance d’une exécution nécessitent également le droit Manage triggers, ou le droit de gérer les déclencheurs du scope de l’exécution, pour l’utilisateur à l’origine de l’appel.

Sur cette page