Connecter votre application à une automatisation

Envoyez un événement applicatif lorsque quelque chose se produit dans votre système, par exemple la création d'une commande ou la réception d'un paiement. Un événement peut démarrer une exécution, reprendre une exécution en attente ou annuler une exécution correspondant à une règle d'annulation. Chaque automatisation dispose d'une seule URL d'événement pour ces trois usages.

Automations is in Early access. Your workspace permissions determine which actions you can perform.

Si vous ne pouvez pas ouvrir Automations ou créer un brouillon, consultez les contrôles d'accès et de modification de l'espace de travail.

Configurer l'événement qui démarre une exécution

Créez une automation avec Event from your application comme déclencheur.
Définissez Event name, par exemple order.created. Les noms sont sensibles à la casse et peuvent contenir des lettres, des chiffres, des points, des tirets bas ou des tirets.
Définissez Event fields pour les données envoyées par votre application. Pour une commande, ajoutez un champ de type chaîne nommé order_id. Les étapes suivantes peuvent utiliser ces champs.
Publiez l'automation. L'écran de confirmation affiche How to start a run, avec l'URL de l'événement et un exemple de requête.

Pour retrouver les détails de connexion, sélectionnez le déclencheur et cliquez sur How to connect your application dans l'édition rapide. L'éditeur étendu affiche les contrôles de connexion.

Simuler un brouillon ou exécuter la version publiée

Utilisez Preview workflow avec des données d'exemple pour simuler votre brouillon sans envoyer de messages ni modifier de données. Exécuter la commande cURL, cliquer sur Send event… ou utiliser Start run exécute l'automation publiée et peut effectuer des actions réelles. Les modifications de brouillon enregistrées ou non ne s'appliquent pas à ces exécutions.

Publiez l'automation avant d'envoyer des événements. Si elle n'a pas de version publiée, la requête est rejetée immédiatement ; l'événement n'est ni mis en file d'attente ni conservé. Les exemples de l'éditeur peuvent refléter les modifications du brouillon : publiez ces modifications avant d'envoyer des données qui en dépendent.

Copier l'URL et envoyer un événement

Utilisez Copy request pour obtenir une commande cURL contenant l'URL, les en-têtes et un corps d'exemple. Remplacez les valeurs d'exemple par les données de votre application.

L'URL inclut les identifiants de l'espace de travail et de l'automation :

Exemple de code

POST https://<your-regional-api-host>/v1/hooks/automations/<workspace-id>/<automation-id>

Utilisez l'URL complète copiée depuis le tableau de bord. Vous n'avez pas besoin d'un en-tête X-Workspace-Id. L'option d'authentification actuelle est No authentication : toute personne disposant de cette URL peut envoyer des événements. Conservez-la dans la configuration de votre serveur.

Pour une automation configurée pour order.created, définissez AUTOMATION_EVENT_URL sur l'URL copiée et envoyez :

Exemple de code

curl --request POST "$AUTOMATION_EVENT_URL" \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "order.created",
    "data": { "order_id": "order_123" }
  }'

Définissez type sur le nom d'événement configuré et data sur un objet correspondant aux champs de l'événement. Vous pouvez aussi fournir occurred_at sous forme d'horodatage RFC 3339 ; la valeur par défaut est l'heure d'arrivée de l'événement.

Une réponse 202 Accepted avec status: "queued" confirme que l'événement est en file d'attente. Bird génère l'identifiant de l'événement et le renvoie dans event_id. Ouvrez l'onglet Runs de l'automation pour inspecter l'exécution. L'acceptation en file d'attente ne confirme pas que l'événement a correspondu à un déclencheur ni qu'une exécution a démarré.

Vous pouvez aussi utiliser Send event… dans le tableau de bord pour soumettre l'exemple sans terminal. Cela envoie un événement réel.

Reprendre une exécution en attente d'un événement

Une étape en attente utilise la même URL d'automation que le déclencheur. Son nom d'événement et subject_key identifient ce qui s'est passé et quelle exécution doit le recevoir.

Dans Automation settings, activez Skip overlapping runs et Use a business key. Définissez Business key sur une valeur qui identifie la commande, la facture ou un autre objet. Pour l'exemple de commande, utilisez l'expression trigger.data.data.order_id.
Ajoutez Wait for application event et configurez son nom d'événement, ses champs d'événement et son délai d'expiration. Par exemple, attendez order.paid avec un champ chaîne payment_id.
Publiez, envoyez l'événement de démarrage et attendez que son exécution apparaisse dans Runs.
Envoyez l'événement de suivi à la même URL, avec subject_key égal à la clé métier de l'exécution :

Exemple de code

{
  "type": "order.paid",
  "subject_key": "order_123",
  "data": { "payment_id": "payment_456" }
}

subject_key est la valeur de la clé métier, par exemple order_123 ; ce n'est ni l'identifiant de l'événement ni l'identifiant de l'exécution. La vue de connexion détaillée de l'étape d'attente affiche des indications pour votre clé configurée.

Un événement correspondant peut être capturé après le démarrage de l'exécution, même avant qu'elle atteigne l'étape en attente. Les événements traités avant l'existence d'une exécution correspondante ne sont pas conservés pour une exécution future. Une attente avec un filtre ne reprend que lorsque les champs de l'événement et le filtre correspondent tous les deux. L'exécution emprunte le chemin d'expiration si aucun événement éligible n'est traité avant l'échéance.

Les règles d'annulation dans Automation settings utilisent aussi cette URL. Une règle peut cibler toutes les exécutions actives de l'automation ou l'exécution correspondant à subject_key. Configurez un filtre pour limiter les exécutions qu'elle annule. L'annulation ne peut pas défaire une action déjà effectuée.

Versions publiées et automations en pause

Les nouvelles exécutions utilisent la version active au moment du traitement de l'événement. Les exécutions existantes conservent leur version d'origine, y compris leurs champs d'événement et leurs conditions d'attente. Publier un format d'événement modifié ne met pas à jour les exécutions déjà démarrées.

Mettre en pause une automation publiée empêche les nouvelles exécutions. Les événements peuvent toujours reprendre ou annuler les exécutions existantes pendant la pause.

Gérer la livraison et les nouvelles tentatives

Les événements sont traités de manière asynchrone et peuvent faire l'objet de nouvelles tentatives ou être traités dans le désordre. Attendez que l'exécution de démarrage existe avant d'envoyer un événement de suivi. Le occurred_at d'un événement ne contrôle pas l'ordre de traitement, ne prolonge pas une attente et n'empêche pas une expiration.

La protection contre les nouvelles tentatives est limitée dans le temps. Si les enregistrements de tentatives expirent ou sont perdus, un événement peut être traité à nouveau, potentiellement avec une version plus récente ou une exécution active différente. Concevez votre application pour tolérer les événements en double.

Pour activer la protection contre les doublons, fournissez un Idempotency-Key lors de la première tentative, puis réutilisez-le avec la même URL et un corps de requête inchangé pour les nouvelles tentatives. Utilisez une nouvelle clé pour chaque nouvelle requête. Un rejeu renvoie le même event_id. Le guide d'idempotence explique la fenêtre de rejeu limitée et les réponses de conflit.

Dépanner un événement

La requête renvoie 4xx : Vérifiez les détails d'erreur de la réponse, l'URL, ainsi que les champs obligatoires type et objet data. Envoyez Content-Type: application/json. Le corps de la requête entier doit tenir dans 25 Ko (25 000 octets) ; les corps plus volumineux renvoient 413.
L'automation n'a pas été publiée : Publiez-la avant d'envoyer un événement. L'événement rejeté n'est pas conservé ; envoyez une nouvelle requête après la publication.
La requête renvoie 202 mais aucune exécution ne démarre : Vérifiez que l'automatisation est active, que le nom de l'événement correspond à son déclencheur et que les données correspondent aux champs d'événement publiés. La protection contre les chevauchements peut ignorer une nouvelle exécution tant qu'une autre est active. Vérifiez aussi le quota mensuel d'exécutions ; les démarrages ignorés à la limite ne sont pas mis en file d'attente pour le mois suivant.
L'exécution reste à une étape en attente : Vérifiez le nom d'événement, la clé métier exacte, les champs de données, le filtre et le délai d'expiration. Utilisez le format d'événement de la version publiée d'origine de l'exécution.
Une nouvelle tentative renvoie un conflit : Réessayez avec la clé d'origine et la requête inchangée. Si vous souhaitez envoyer un événement différent, utilisez une nouvelle clé.

L'enveloppe de la requête est vérifiée avant la mise en file d'attente. Les données de l'événement sont vérifiées par rapport au déclencheur, à l'attente et aux règles d'annulation pendant le traitement : un événement en file d'attente peut donc ne correspondre à aucun d'entre eux.

Étapes suivantes

Ouvrez Automations pour configurer et publier votre workflow.
Gérez les nouvelles tentatives idempotentes dans votre application.
Attendez un événement dans un workflow en cours d'exécution.
Parcourez les guides Automations.

Ressources associées

Poursuivez avec la documentation, les guides et les exemples sur ce sujet. Les ressources sont en anglais.

Guide d'implémentationPreview your first automation