Déclencheurs d’automatisation

Un déclencheur, c’est ce qui lance une automatisation quand personne ne clique nulle part. Il en existe exactement trois sortes, l’ensemble est fermé, et une automatisation porte un seul déclencheur à la fois — en lier une autre sorte remplace celui qu’elle a. Le plus utile à savoir sur un déclencheur : il se rattache au nom de l’automatisation et non à une version. C’est pour cela que mettre une nouvelle version en service n’invalide jamais une URL de webhook dont dépend un système externe, et ne fait jamais disparaître une planification.

Chaque déclencheur lance la version en service et s’exécute en mode réel : une automatisation sans version en service ne peut donc pas être lancée par l’un d’eux. Chaque déclencheur porte un interrupteur et retient la dernière fois que le planificateur a agi dessus.

Les trois sortes

Un démarrage programmatique n'a besoin d'aucun déclencheur : un client d'API avec une clé d'organisation appelle POST /api/v1/automations/{name}/runs (ou l'outil MCP start_run), et la clé elle-même est le droit d'entrée — voir la référence API.

Planifications

Une planification porte une expression cron à cinq champs et le fuseau IANA dans lequel elle est lue. Les champs sont la minute, l’heure, le jour du mois, le mois et le jour de la semaine, et chacun accepte un *, un nombre, une plage, un pas, ou une liste de ceux-ci séparée par des virgules.

*/15 * * * *     toutes les quinze minutes
0 9 * * 1-5      09:00 en semaine
0 6 1 * *        06:00 le premier du mois
30 8 1 * 1       08:30 le 1er et chaque lundi

Le jour de la semaine va de 0 à 7, où 0 comme 7 désignent le dimanche. Quand tu restreins à la fois le jour du mois et le jour de la semaine, un jour correspondant à l’un ou à l’autre déclenche — la règle même de crontab, et celle qui fait que le dernier exemple se lit comme il se comporte.

Le fuseau est résolu en heure locale : une planification écrite pour 09:00 dans Europe/Zurich reste à 09:00 au passage à l’heure d’été, au lieu de dériver d’une heure deux fois par an. Une planification qui ne nomme aucun fuseau est lue en UTC.

La résolution est d’une minute, et une planification est un battement de cœur, pas une file d’attente : après une panne, l’automatisation repart à sa prochaine échéance au lieu de rejouer celles qu’elle a manquées. Une planification dont l’expression cron ne se lit pas est ignorée plutôt que d’arrêter les autres planifications de la plateforme — sa date de dernier déclenchement cesse simplement d’avancer, et c’est le signal d’aller la relire.

Webhooks

Un webhook est une URL entrante protégée par un token. Sa création engendre le token et l’affiche une seule fois ; seul son empreinte est stockée, de sorte que la plateforme peut vérifier un appelant sans jamais pouvoir reconstituer l’URL. Tout système qui y poste lance une exécution, et le corps de la requête devient la charge utile de l’exécution.

curl -X POST https://<ton-hote-tale>/api/automations/webhook/<token> \
  -H 'Content-Type: application/json' \
  -d '{"invoiceId": "inv-1"}'

Un appel réussi est accepté immédiatement et répond avec l’id de l’exécution lancée : l’appelant n’attend donc jamais que l’automatisation se termine. Un corps qui n’est pas du JSON est transmis tel quel en texte plutôt que refusé, car certains fournisseurs postent des charges utiles en formulaire ou en texte brut. Les corps sont plafonnés à 256 Ko : un webhook reçoit une charge utile, pas un téléversement.

Les livraisons sont idempotentes, parce que chaque fournisseur livre au moins une fois — une réponse lente, une connexion coupée ou quelqu’un qui clique sur renvoyer expédie la même livraison une seconde fois. Une requête qui nomme sa livraison (Idempotency-Key, le webhook-id des Standard Webhooks, X-GitHub-Delivery et les autres en-têtes courants des fournisseurs) reste connue pendant 24 heures : une répétition avec le même identifiant répond avec l’exécution que la première a lancée, marquée duplicate: true, au lieu d’en lancer une seconde. Une requête sans identifiant est reconnue à son corps — un corps identique à l’octet, posté sur la même URL en moins de deux minutes, est la même livraison. Des livraisons distinctes s’exécutent chacune ; si tes charges utiles peuvent légitimement se répéter en moins de deux minutes, envoie un identifiant. Webhooks donne la liste complète des en-têtes et les formes de réponse.

Tu peux restreindre l’exécution à un projet en ajoutant ?projectId=<id> à l’URL — le projet que tu intègres dans l’URL donnée au fournisseur. Omets-le et l’exécution utilise la liaison de l’automatisation elle-même : une automatisation liée à un seul projet s’y exécute, une liée à plusieurs ou à aucun s’exécute sur toute l’organisation. Le projet est vérifié contre ces liaisons, de sorte qu’une URL publique ne peut jamais étendre l’exécution au-delà de ce à quoi l’automatisation est liée ; un projet hors de l’ensemble répond par un 400.

Deux refus valent la peine d’être reconnus. Un token inconnu et le token d’un déclencheur éteint répondent volontairement de la même manière, pour que personne ne puisse sonder la plateforme afin de savoir quels tokens existent. Une automatisation sans version en service répond plutôt par un conflit, ce qui te dit que l’URL va bien et que c’est la mise en service qui manque.

Événements

Un déclencheur d’événement nomme un événement de la plateforme et se déclenche dès que cet événement se produit dans l’organisation. La charge utile de l’événement devient l’entrée de l’exécution, ce qui en fait la sorte vers laquelle se tourner quand le travail de l’automatisation est de réagir à quelque chose que la plateforme vient de faire elle-même.

Ce que chaque sorte transporte dans l’exécution

L’entrée que reçoit une automatisation dit quelle sorte l’a lancée : un même document peut donc servir plusieurs déclencheurs et se brancher sur la différence.

Une exécution démarrée par l'API porte exactement l'input envoyé par l'appelant.

Déclare la forme attendue dans le schéma inputs du document, et la référence qui la lit est vérifiée avant même que l’automatisation ne s’exécute.

La mise en service ne les dérange pas

Parce qu’un déclencheur nomme l’automatisation plutôt qu’une version, l’ensemble survit à chaque mise en service et à chaque retour arrière. Publie une URL de webhook auprès d’un partenaire, mets onze versions de plus en service, reviens deux fois en arrière : cette URL continue de fonctionner et atteint chaque fois ce qui est en service à ce moment-là.

L’inverse est vrai aussi : ajouter, modifier ou retirer un déclencheur ne change rien au document ni à ses versions. Déclencheurs et versions sont deux choses indépendantes à propos de la même automatisation.

En éteindre un sans le perdre

Chaque déclencheur a un interrupteur, et l’éteindre est la façon d’empêcher une automatisation de se lancer sans rien abandonner. Une planification éteinte n’arrive plus à échéance, une URL de webhook éteinte n’est plus honorée, et un déclencheur d’événement éteint ne correspond plus — tandis que la ligne, sa configuration et tout l’historique des exécutions de l’automatisation restent exactement où ils étaient. Rallume-le et il repart.

Supprimer un déclencheur est la version définitive du même geste, et pour un webhook c’est aussi la façon de révoquer l’URL. Prends l’interrupteur quand tu veux une pause, et la suppression quand tu veux que l’identifiant disparaisse.

Où cela s’inscrit

Trois sortes, un seul comportement : chacune lance la version en service en mode réel, chacune retient son dernier déclenchement, et chacune se met en pause sans être perdue — et aucune ne se soucie du nombre de mises en service depuis. Concepts d’automatisation explique pourquoi le rattachement au nom rend cela vrai ; Journaux d’exécution montre les exécutions que tes déclencheurs ont produites et laquelle a lancé chacune.