Déclencheurs et webhooks

Démarrez un workflow lorsqu'un événement se produit dans un outil externe. Un webhook est un endpoint HTTP qui reçoit des événements d'un fournisseur tiers comme Slack, GitHub ou Notion. Un trigger associe une source d'événements à une action — ici, le démarrage d'un workflow.

Ce guide décrit le flux de bout en bout :

Créez une source d'événements webhook pour Slack, GitHub ou Notion.
Créez un workflow qui accepte le payload du webhook.
Créez un trigger qui associe le webhook au workflow.
Configurez le fournisseur pour envoyer les événements à l'URL du webhook générée.
Envoyez un événement de test réel ou signé, puis vérifiez que le workflow démarre.

Prérequis

Un compte Mistral et une clé API, exportée en tant que MISTRAL_API_KEY.
Un workflow déployé qui accepte un payload générique. Suivez Guide de démarrage : construire votre premier workflow pour en créer un, et Démarrer avec les déploiements gérés pour le déployer.

Étape 1 : créer un webhook

Créez une source d'événements webhook depuis la page Webhooks d'AI Studio, ou avec POST /v1/webhooks. Dans l'API, le champ provider sélectionne le type de source d'événements, secret est le secret de signature utilisé pour authentifier les événements entrants, et owner_type restreint le webhook à votre espace de travail :

curl -X POST https://api.mistral.ai/v1/webhooks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -d '{
    "provider": "slack",
    "name": "My Slack webhook",
    "secret": "your-slack-signing-secret",
    "owner_type": "workspace"
  }'

curl -X POST https://api.mistral.ai/v1/webhooks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -d '{
    "provider": "slack",
    "name": "My Slack webhook",
    "secret": "your-slack-signing-secret",
    "owner_type": "workspace"
  }'

Conservez l'URL du webhook renvoyée par l'API. Vous l'enregistrez côté fournisseur à l'étape 4.

Avertissement

Ne placez jamais un secret de signature réel dans un commit et ne le collez jamais dans un document partagé. Utilisez un secret temporaire pour les tests, et renouvelez-le en supprimant puis en recréant le webhook s'il est exposé.

Étape 2 : créer un workflow

Créez et déployez un workflow qui accepte le payload du webhook. Consultez Guide de démarrage : construire votre premier workflow.

Les payloads des webhooks varient selon le fournisseur et le type d'événement ; l'entrée du workflow doit donc être générique :

from typing import Any

from pydantic import BaseModel

import mistralai.workflows as workflows


class GenericPayload(BaseModel):
    value: Any = None


@workflows.workflow.define(name="webhook-hello")
class WebhookWorkflow:
    @workflows.workflow.entrypoint
    async def run(self, input: GenericPayload) -> str:
        # Process input.value or the normalized webhook payload here.
        return "ok"

from typing import Any

from pydantic import BaseModel

import mistralai.workflows as workflows


class GenericPayload(BaseModel):
    value: Any = None


@workflows.workflow.define(name="webhook-hello")
class WebhookWorkflow:
    @workflows.workflow.entrypoint
    async def run(self, input: GenericPayload) -> str:
        # Process input.value or the normalized webhook payload here.
        return "ok"

Avertissement

Utilisez le nom du workflow lors de la création du trigger, et non son ID. Assurez-vous que le déploiement souhaité est actif avant de tester. Si plusieurs déploiements sont actifs, le trigger ne parvient pas à démarrer le workflow.

Étape 3 : créer un trigger

Créez un trigger qui démarre le workflow lorsque le webhook reçoit un événement, depuis la page Triggers d'AI Studio, ou avec POST /v1/triggers :

curl -X POST https://api.mistral.ai/v1/triggers \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -d '{
    "title": "My workflow trigger",
    "event_source_id": "<webhook-id-from-step-1>",
    "handler": "workflows",
    "action": {
      "primitive_id": "<workflow-name>",
      "type": "start_workflow"
    },
    "owner_type": "workspace",
    "filters": null
  }'

curl -X POST https://api.mistral.ai/v1/triggers \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -d '{
    "title": "My workflow trigger",
    "event_source_id": "<webhook-id-from-step-1>",
    "handler": "workflows",
    "action": {
      "primitive_id": "<workflow-name>",
      "type": "start_workflow"
    },
    "owner_type": "workspace",
    "filters": null
  }'

title : un titre lisible pour identifier le trigger.
event_source_id : l'ID du webhook créé à l'étape 1.
handler : workflows exécute un workflow.
action : primitive_id est le nom du workflow, et type est start_workflow.

Conservez l'ID du trigger pour le nettoyage et le débogage.

Note

Le workflow s'exécute sous l'identité de l'utilisateur qui a créé le trigger, et non sous celle de la personne à l'origine de l'événement du fournisseur. Les triggers ne peuvent pas démarrer de workflows on-behalf-of (OBO).

Filtres optionnels

Les filtres restreignent les événements qui démarrent le workflow. Les expressions de filtre suivent la syntaxe JMESPath. Quel que soit le fournisseur, chaque événement possède un champ event_type, sur lequel vous pouvez donc toujours filtrer :

# Slack
event_type == 'message.channels' && author == 'octocat' && channel != 'general'

# GitHub
event_type == 'pull_request' && repository.name == 'dashboard' && pusher.name == 'octocat'

# Slack
event_type == 'message.channels' && author == 'octocat' && channel != 'general'

# GitHub
event_type == 'pull_request' && repository.name == 'dashboard' && pusher.name == 'octocat'

Note

La propriété de filtre est une chaîne entre guillemets doubles, et les valeurs filtrées (par exemple 'message.channels') doivent être entre guillemets simples.

La syntaxe des filtres et les noms de champs normalisés peuvent varier selon la version de l'implémentation. Si un filtre est rejeté ou ne trouve jamais de correspondance, examinez l'événement normalisé et comparez-le au comportement de correspondance des triggers et au schéma des événements de la version actuelle de l'API.

Étape 4 : configurer le fournisseur

Utilisez l'URL du webhook renvoyée par l'API pour configurer le fournisseur. Une vérification d'URL propre au fournisseur peut être requise avant que les événements ne soient acceptés.

Configurez l'URL de requête dans votre application Slack.

Avertissement

Traitez le secret de signature Notion renvoyé comme une donnée sensible. Une fois la vérification d'URL terminée, Notion peut envoyer des événements au webhook, et le secret stocké authentifie les livraisons suivantes.

Étape 5 : envoyer un événement de test

Envoyez un événement de test réel ou signé depuis le fournisseur, puis vérifiez que le workflow démarre en consultant ses exécutions dans la Console Mistral.

Nettoyage

Supprimez le trigger avant de supprimer son webhook :

curl -X DELETE https://api.mistral.ai/v1/triggers/<trigger-id> \
  -H "Authorization: Bearer $MISTRAL_API_KEY"

curl -X DELETE https://api.mistral.ai/v1/webhooks/<webhook-id> \
  -H "Authorization: Bearer $MISTRAL_API_KEY"

curl -X DELETE https://api.mistral.ai/v1/triggers/<trigger-id> \
  -H "Authorization: Bearer $MISTRAL_API_KEY"

curl -X DELETE https://api.mistral.ai/v1/webhooks/<webhook-id> \
  -H "Authorization: Bearer $MISTRAL_API_KEY"

En production

Les triggers démarrent les workflows sur un déploiement. Pour exécuter le workflow sur Mistral Cloud, suivez Démarrer avec les déploiements gérés. Consultez Déploiements gérés pour l'ensemble du processus de déploiement.
Stockez les identifiants dans Secrets plutôt que dans le code du workflow.

Aller plus loin

Déclencheurs et webhooks

Planification des workflows