Déclencheur Route d'une API

Le type Route d'une API expose un point d'accès HTTP : chaque requête valide déclenche le flux associé en lui transmettant la requête (méthode, en-têtes, corps, …).

Webhooks

Un webhook — mécanisme par lequel un service externe envoie des événements via HTTP — se configure avec ce type : il n'existe pas de type de déclencheur séparé « Webhook ». Choisissez la méthode POST (souvent imposée par le prestataire) et un path dédié (ex. /webhooks/stripe), déployez, puis enregistrez l'URL complète fournie par Ecosystem dans la console du service tiers.

Paramètres

Paramètre	Type	Obligatoire	Défaut	Description
Nom	Chaîne	✅	—	Libellé du déclencheur ; préremplit automatiquement le Chemin (slug).
Chemin (slug)	Chaîne	✅	—	Identifiant de l'URL, prérempli depuis le Nom, modifiable.
Méthodes HTTP	Liste	✅	—	Méthodes acceptées : GET, POST, PUT, DELETE, PATCH, HEAD (une ou plusieurs).
Path	Chaîne	❌	—	Chemin complémentaire de l'endpoint (Custom Path), avec paramètres dynamiques possibles.
Headers	Paires clé-valeur	❌	—	En-têtes attendus sur les requêtes entrantes.
Format de réponse attendu	example / JSONSchema	❌	—	Contrat de réponse attendu pour les consommateurs de l'API.

Personnaliser le Path

Le champ Path (Custom Path) définit le chemin HTTP exposé en complément du slug. L'URL publique combine le slug et le path :

https://<environnement>/<slug><path>

Élément	Exemple	Rôle
Slug	api.reception.commandes	Identifie le déclencheur dans Ecosystem
Path	/orders/:id	Route complémentaire, avec paramètres éventuels
URL complète	…/api.reception.commandes/orders/1234	Requête reçue par le déclencheur

La syntaxe suit les conventions de routage Express.js :

Syntaxe	Exemple de path	Effet
Segment fixe	/orders	Correspond exactement à ce chemin
Paramètre :nom	/order/:id	Capture un segment dans incomingRequest.params.nom
Paramètre optionnel :nom?	/:id?	Accepte la requête avec ou sans ce segment
Wildcard *nom	/orders/*path	Capture tout le reste du chemin après le préfixe

Segment fixe — un path sans paramètre correspond exactement à l'URL demandée (hors query string) :

Path configuré	Requête acceptée	Requête refusée
/orders	POST /orders	POST /orders/42
/webhooks/stripe	POST /webhooks/stripe	POST /webhooks/stripe/events

Paramètre personnalisé (:nom) — un segment préfixé par : capture une valeur variable, exposée dans incomingRequest.params :

Requête	Valeur capturée
GET /order/1234	incomingRequest.params.id → '1234'
GET /order/abc-def	incomingRequest.params.id → 'abc-def'

// Pour une requête GET /order/1234
incomingRequest.params.id // '1234'

Une colonne id est ajoutée automatiquement dans les vues de données du déclencheur.

Paramètre optionnel (:nom?) — ajoutez ? après le nom du paramètre pour le rendre optionnel :

Requête	Valeur capturée
GET /1234	incomingRequest.params.id → '1234'
GET /	incomingRequest.params.id → undefined

// Requête GET /1234
incomingRequest.params.id // '1234'

// Requête GET / (path vide)
incomingRequest.params.id // undefined

Utile pour un endpoint unique qui gère à la fois une ressource identifiée et une collection.

Wildcard (*nom) — *nom accepte tout le reste du chemin après un préfixe fixe ; la portion capturée est une chaîne (segments séparés par /) :

Requête	Valeur capturée
GET /orders/1234/delivery	incomingRequest.params.path → '1234/delivery'
GET /orders/a/b/c	incomingRequest.params.path → 'a/b/c'

// Requête GET /orders/1234/delivery
incomingRequest.params.path // '1234/delivery'

Convient aux APIs de type « catch-all » : proxy, fichiers imbriqués, routes dont la profondeur varie.

Bonnes pratiques sur le Path

• Préfixez les paths par une version ou un domaine métier : /v1/orders/:id plutôt que /:id.
• Validez incomingRequest.params dans le flux (présence, format, valeurs autorisées), surtout pour les paramètres optionnels (undefined).
• Les query strings (?foo=bar) ne font pas partie du path : utilisez incomingRequest.query.
• Évitez les wildcards trop larges en production.

Exemple de données d'entrée

La section Exemple du formulaire décrit le schéma ou l'exemple des données que le déclencheur est censé recevoir :

{
  "orderId": "CMD-4821",
  "customer": { "id": "CUS-77", "email": "client@exemple.com" },
  "total": 149.9
}

Cette section sert de référence aux intégrateurs qui appellent votre déclencheur. Si la validation est activée et que les données reçues ne respectent pas le schéma, le flux ne se lance pas et une erreur est renvoyée. L'exemple peut être déduit d'un fichier Swagger importé ou saisi manuellement.

En activant la validation des données, une interface permet de définir, pour chaque champ, son schéma de validation :

Champ	Description
Nom	Nom du champ.
Description	Description du champ attendu.
Exemple	Exemple de valeur pour le champ.
Type	Type attendu : chaîne de caractères, nombre, booléen, objet, tableau, nombre entier.
Masquer	Masque le champ (ex. mot de passe, secret).
Requis	Indique si le champ est obligatoire.

Entrée

Le déclencheur reçoit la requête HTTP entière : méthode, path, query string, en-têtes et corps.

{
  "method": "POST",
  "url": "https://api.example.com/api.reception.commandes/orders/1234?lang=fr",
  "query": { "lang": "fr" },
  "params": { "id": "1234" },
  "headers": { "content-type": "application/json" },
  "body": { "orderId": "CMD-4821", "total": 149.9 }
}

Sortie

Le flux accède au corps de la requête via data, et aux métadonnées via incomingRequest :

Propriété	Description
data	Corps de la requête, parsé en JSON.
incomingRequest.method	Méthode HTTP de la requête.
incomingRequest.url	URL complète de la requête.
incomingRequest.query	Paramètres de query string.
incomingRequest.params	Paramètres de path capturés (:id, :id?, *path).
incomingRequest.headers	En-têtes HTTP reçus.

Depuis un nœud suivant : {{data.orderId}} ou {{incomingRequest.params.id}}.

Erreurs

• Requête refusée — un path qui ne correspond pas au pattern configuré (segment fixe, paramètre, wildcard) ne déclenche pas le flux : la requête est rejetée.
• Paramètre optionnel absent — incomingRequest.params.id vaut undefined : validez sa présence dans le flux avant de l'utiliser.

Exemple

Réception de commandes : créez un déclencheur de type Route d'une API (méthode POST, path /orders), associez un flux qui valide le corps puis traite la commande, et déployez. Chaque POST /orders lance le flux.

Consulter une commande : créez un déclencheur GET avec path /orders/:id ; le flux lit incomingRequest.params.id, charge la commande et répond via un nœud Réponse HTTP.

Voir aussi

• Nœud Déclencheur — données reçues et accès à incomingRequest
• Méthodes d'authentification
• Patterns d'utilisation
• Autres types de déclencheurs