Triggers and webhooks

Start a workflow when something happens in an external tool. A webhook is an HTTP endpoint that receives events from a third-party provider. A trigger binds an event source to an action — here, starting a workflow.

Supported providers

What you'll do

This guide walks through the end-to-end flow:

1. Create a webhook event source for Slack, GitHub, or Notion.
2. Create a workflow that accepts the webhook payload.
3. Create a trigger that maps the webhook to the workflow.
4. Configure the provider to send events to the generated webhook URL.
5. Send a real or signed test event and verify that the workflow starts.

• A Mistral account and an API key, exported as MISTRAL_API_KEY.
• A deployed workflow that accepts a generic payload. Follow Quickstart: build your first workflow to create one, and Quickstart: deploy a workflow to Mistral to deploy it.

Create a webhook event source from the Webhooks page in AI Studio, or with POST /v1/webhooks. In the API, the provider field selects the event source type, secret is the signing secret used to authenticate incoming events, and owner_type scopes the webhook to your 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"
  }'

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"
  }'

Save the webhook URL returned by the API. You register it on the provider side in Step 4.

Create and deploy a workflow that accepts the webhook payload. See Quickstart: build your first workflow.

The workflow receives the incoming HTTP request as its input. Nothing is mapped or templated — the input is the whole request:

{
  "method": "POST",
  "path": "/",
  "headers": { "content-type": "application/json", "x-github-event": "pull_request" },
  "query_params": {},
  "body": { "action": "opened", "pull_request": { "..." : "..." } },
  "raw_body": "{\"action\":\"opened\", ...}"
}

{
  "method": "POST",
  "path": "/",
  "headers": { "content-type": "application/json", "x-github-event": "pull_request" },
  "query_params": {},
  "body": { "action": "opened", "pull_request": { "..." : "..." } },
  "raw_body": "{\"action\":\"opened\", ...}"
}

Typed inputs

The workflows triggers plugin (mistralai-workflows-plugins-triggers) provides typed input models for each provider:

A provider Event validates into the class matching the payload (for example github.PullRequestOpened, github.Push, slack.AppMentioned), with body parsed into the provider's model. Events without a dedicated class validate as the provider's EventReceived, with an untyped body.

import mistralai.workflows as workflows
from mistralai.workflows.plugins.triggers import github


@workflows.workflow.define(name="pr-triage")
class PrTriageWorkflow:
    @workflows.workflow.entrypoint
    async def run(self, event: github.Event) -> str:
        match event:
            case github.PullRequestOpened(body=body):
                # body.pull_request is typed
                ...
                return "ok"
            case _:
                return "ignored"

import mistralai.workflows as workflows
from mistralai.workflows.plugins.triggers import github


@workflows.workflow.define(name="pr-triage")
class PrTriageWorkflow:
    @workflows.workflow.entrypoint
    async def run(self, event: github.Event) -> str:
        match event:
            case github.PullRequestOpened(body=body):
                # body.pull_request is typed
                ...
                return "ok"
            case _:
                return "ignored"

For other providers, TriggerEvent exposes the raw request with helpers to read a header and parse the body:

from pydantic import BaseModel

import mistralai.workflows as workflows
from mistralai.workflows.plugins.triggers import TriggerEvent


class Payload(BaseModel):
    id: str


@workflows.workflow.define(name="on-event")
class OnEvent:
    @workflows.workflow.entrypoint
    async def run(self, event: TriggerEvent) -> None:
        if event.header("x-event-type") != "created":
            return
        payload = event.parse_body(Payload)
        ...

from pydantic import BaseModel

import mistralai.workflows as workflows
from mistralai.workflows.plugins.triggers import TriggerEvent


class Payload(BaseModel):
    id: str


@workflows.workflow.define(name="on-event")
class OnEvent:
    @workflows.workflow.entrypoint
    async def run(self, event: TriggerEvent) -> None:
        if event.header("x-event-type") != "created":
            return
        payload = event.parse_body(Payload)
        ...

Create a trigger that starts the workflow when the webhook receives an event, from the Triggers page in AI Studio, or with 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: a human-readable title for the trigger.
• event_source_id: the ID of the webhook created in Step 1.
• handler: workflows runs a workflow.
• action: primitive_id is the workflow name, and type is start_workflow.

Save the trigger ID for cleanup and debugging.

Filters restrict which events start the workflow. Filter expressions follow JMESPath. Every event has an event_type field, whatever the provider, so you can always filter on it:

# 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'

Filter syntax and normalized field names can vary by implementation version. If a filter is rejected or never matches, inspect the normalized event and compare it with the trigger-matching and event-schema behavior of the current API version.

Use the webhook URL returned by the API to configure the provider. Provider-specific URL verification may be required before events are accepted.

Send a real or signed test event from the provider, then verify that the workflow starts by checking its executions in the Mistral Console. You can also check trigger activity through the API with GET /v1/triggers/{trigger_id}/events:

curl -X GET "https://api.mistral.ai/v1/triggers/<trigger-id>/events?limit=100" \
  -H "Authorization: Bearer $MISTRAL_API_KEY"

curl -X GET "https://api.mistral.ai/v1/triggers/<trigger-id>/events?limit=100" \
  -H "Authorization: Bearer $MISTRAL_API_KEY"

Each event is recorded with a status:

Delivery behavior

• One run per delivery. The execution ID is derived from the delivery's dedup key and the action, so retries and redeliveries never start the same workflow twice.
• Retries. Transient failures (no active deployment, rate limit, timeout, 5xx) are retried up to 4 times, after 60s, 180s, then 600s. Permanent failures (workflow not found, 4xx) are not retried. The event then shows as TRIGGER_FAILED with the reason in detail.
• Asynchronous. The provider gets its response once the event is accepted, before the workflow starts. The workflow's result is never sent back to the provider.

Delete the trigger before deleting its webhook (the webhook returns 409 if triggers still reference it):

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"

The signing secret can't be changed after creation. To rotate it, create a new webhook, recreate your triggers on it, and update the URL and secret in the provider.

Managing webhooks

Managing triggers

• Triggers start workflows on a deployment. To run the workflow on Mistral Cloud, follow Quickstart: deploy a workflow to Mistral. See Managed deployments for the full deploy path.
• Store credentials in Secrets rather than in workflow code.