Webhook Triggers

Webhook triggers let external systems start runs via HTTP POST. Three types:

Type	What it triggers	Payload
Task webhook	Runs a pre-created task	Optional JSON body (task has its own instructions)
Agent webhook	Starts a new dynamic run	Requires `{"message": "..."}` in body
App trigger	Runs a task on app events	Automatic, Composio delivers event data

Same work every time → task webhook. Different message per trigger → agent webhook. Connected app fires it → app trigger.

Task Webhooks

Attach a webhook trigger to a task, then POST to the generated URL to run it:

Python

from m8tes import M8tes

client = M8tes()

task = client.tasks.create(agent_id=1, instructions="Generate the weekly sales report")
trigger = client.tasks.triggers.create(task_id=task.id, type="webhook")
print(trigger.url)  # https://api.m8tes.ai/api/v1/webhooks/tasks/{id}/{token}

Any system can now trigger it. The body is optional; the task already has its instructions:

import requests

requests.post(trigger.url)  # simple trigger
requests.post(trigger.url, json={"context": "Include data from last 7 days"})

curl -X POST https://api.m8tes.ai/api/v1/webhooks/tasks/1/tok_abc123 \
  -H "Content-Type: application/json" \
  -d '{"context": "Include data from last 7 days"}'

Disable the webhook when you no longer need it; if the URL leaked, re-enabling rotates it (fresh token, old URL dead):

Python

client.tasks.disable_webhook(task_id=1)
hook = client.tasks.enable_webhook(task_id=1)   # new URL

Agent Webhooks

Enable a webhook directly on an agent. Each POST creates a new run with the message you provide:

Python

webhook = client.agents.enable_webhook(1)
print(webhook.url)  # https://api.m8tes.ai/api/v1/webhooks/mates/1/tok_...

client.agents.disable_webhook(1)   # turn it off again

Important: The webhook URL contains a secret token and is only shown once. Store it securely.

POST a JSON body with a message field; the agent processes it with its configured instructions and tools:

import requests

requests.post(webhook.url, json={"message": "New support ticket: User cannot reset password"})

curl -X POST https://api.m8tes.ai/api/v1/webhooks/mates/1/tok_abc123 \
  -H "Content-Type: application/json" \
  -d '{"message": "New support ticket: User cannot reset password"}'

App Triggers

App triggers start task runs when events occur in your connected apps (GitHub, Slack, ...). No webhook URL management: connect the app, pick an event, and Composio delivers it.

Python

# 1. Discover the events a connected app supports
for t in client.apps.list_triggers("github"):
    print(t.slug, t.description)
    # GITHUB_COMMIT_EVENT  On new commit pushed

# 2. Attach one to a task
trigger = client.tasks.triggers.create(
    task_id=task.id,
    type="app",
    app="github",
    trigger_name="GITHUB_COMMIT_EVENT",
    trigger_config={"owner": "acme", "repo": "app"},
    # user_id="end_user_123",   # optional: use this end-user's connection
)

When the event fires, the task runs with the event data injected into its instructions. If the app is disconnected or the connection expires, its triggers are disabled automatically.

Prerequisite: The app must be connected first via client.apps.connect() or the dashboard.

Managing Triggers

Python

for t in client.tasks.triggers.list(task_id=1):
    print(t.id, t.type, t.url)

client.tasks.triggers.delete(task_id=1, trigger_id="schedule_10")

When to use which: example scenarios

Use Case	Type
Automated report on a schedule + manual trigger	Task webhook
CI/CD pipeline triggers a fixed analysis	Task webhook
Slack/Discord bot forwards messages	Agent webhook
Customer support system routes tickets	Agent webhook
Run task on every GitHub push	App trigger
Process new Slack messages automatically	App trigger
React to CRM events (new deal, updated contact)	App trigger

Deduplication: retried deliveries

Include an X-M8tes-Event-Id header so a retried delivery doesn't start a duplicate run:

Python

requests.post(
    webhook.url,
    json={"message": "Process this event"},
    headers={"X-M8tes-Event-Id": "evt_unique_123"},
)

Next: Scheduling · Email Inbox · Webhook Events