Overview

^{Questions or issues? Contact us at api-support@manus.ai.}

Webhooks allow you to receive real-time notifications when important events occur in your Manus tasks. When you register a webhook, Manus will send HTTP POST requests to your specified callback URL whenever these events are triggered.

How Webhook Events Work

When you create and execute tasks, two key lifecycle events can trigger webhook deliveries:

Task Creation: Immediately after a task is successfully created via the API
Task State Change: When a task completes, or requires user input

Each webhook delivery contains a specific event type identifier and a structured payload with relevant task information. Your endpoint will receive these as standard HTTP POST requests that you can process like any other API call.

Setting Up Webhooks

Manage Webhooks

Open Developers settings to create or manage webhooks.

Before activating a webhook, Manus will send a test request to verify your endpoint is accessible and responding correctly. Your endpoint should:

Respond with HTTP status code 200
Accept POST requests with JSON payloads
Respond within 10 seconds

Event Types and Payloads

`task_created` Event

When it triggers: Immediately after a new task is successfully created. Why it’s useful: Allows you to track task creation in your own systems, send confirmation emails, or update dashboards in real-time. Payload Schema:

Field	Type	Required	Description
`event_id`	string	Yes	Unique identifier for this webhook event
`event_type`	string	Yes	Always `"task_created"` for this event
`task_detail`	object	Yes	Task details object
`task_detail.task_id`	string	Yes	Unique identifier for the created task
`task_detail.task_title`	string	Yes	Human-readable title of the task
`task_detail.task_url`	string	Yes	Direct URL to view the task in Manus app

Example Payload:

{
  "event_id": "task_created_task_abc123",
  "event_type": "task_created",
  "task_detail": {
    "task_id": "task_abc123",
    "task_title": "Generate quarterly sales report",
    "task_url": "https://manus.im/app/task_abc123"
  }
}

`task_stopped` Event

When it triggers: When a task reaches a stopping point - either because it completed successfully or needs user input to proceed. Why it’s useful: Essential for knowing when your tasks finish and what the outcome was. Enables automated workflows based on task completion. Payload Schema:

Field	Type	Required	Description
`event_id`	string	Yes	Unique identifier for this webhook event
`event_type`	string	Yes	Always `"task_stopped"` for this event
`task_detail`	object	Yes	Task details object
`task_detail.task_id`	string	Yes	Unique identifier for the task
`task_detail.task_title`	string	Yes	Human-readable title of the task
`task_detail.task_url`	string	Yes	Direct URL to view the task in Manus app
`task_detail.message`	string	Yes	Status message from the task execution
`task_detail.attachments`	array	No	List of files generated by the task
`task_detail.stop_reason`	string	Yes	Why the task stopped: `"finish"` or `"ask"`
`task_detail.question_expectation`	object	No	Question metadata for `stop_reason: "ask"`: webhook-only `event_id` identifying the question event, `options` (empty for free text), `selection_mode` (`"single"` or `"multiple"`), and `response_method` (`"send_message"`). Continue with `task.sendMessage`, not `task.confirmAction`.
`task_detail.structured_output`	object	No	Extracted structured data when the task was created with `structured_output_schema`. Contains `success` (boolean), `value` (your schema), and `error` (string or null). See the Structured Output guide.

question_expectation.event_id identifies the underlying question event, not the webhook notification identified by the top-level event_id. It is not a reply parameter or a send-message idempotency key. In task.listMessages, use the enclosing message’s id; the nested event_id is absent. options contains display text, not option IDs or mandatory exact-match answers. An empty array means free-text input; selection_mode defaults to single and is only a UI hint. For multiple, combine the chosen text into one readable message.content; no delimiter or option-ID array is required, and users may supply their own text. See question replies for a request example and unknown-method handling. Stop Reason Values:

"finish": Task completed successfully and has final results
"ask": Task paused and requires user input or confirmation to continue

Attachment Object Schema:

Field	Type	Required	Description
`file_name`	string	Yes	Name of the generated file
`url`	string	Yes	Secure download URL for the file
`size_bytes`	integer	Yes	File size in bytes

Example Payload (Task Completed):

{
  "event_id": "task_stopped_task_abc123",
  "event_type": "task_stopped",
  "task_detail": {
    "task_id": "task_abc123",
    "task_title": "Generate quarterly sales report",
    "task_url": "https://manus.im/app/task_abc123",
    "message": "I've completed the quarterly sales report analysis. The report includes revenue trends, top-performing products, and regional breakdowns.",
    "attachments": [
      {
        "file_name": "q4-sales-report.pdf",
        "url": "https://s3.amazonaws.com/manus-files/reports/q4-sales-report.pdf",
        "size_bytes": 2048576
      },
      {
        "file_name": "sales-data.xlsx",
        "url": "https://s3.amazonaws.com/manus-files/reports/sales-data.xlsx",
        "size_bytes": 512000
      }
    ],
    "stop_reason": "finish"
  }
}

Example Payload (User Input Required):

{
  "event_id": "task_stopped_task_abc123",
  "event_type": "task_stopped",
  "task_detail": {
    "task_id": "task_abc123",
    "task_title": "Book restaurant reservation",
    "task_url": "https://manus.im/app/task_abc123",
    "message": "I found several restaurants with availability. Which option would you prefer?",
    "attachments": [],
    "stop_reason": "ask",
    "question_expectation": {
      "event_id": "ask_abc123",
      "options": ["Bistro Milano", "Garden Terrace", "The Blue Door"],
      "selection_mode": "single",
      "response_method": "send_message"
    }
  }
}

Integration Examples

Slack Integration

Post task updates directly to Slack channels:

// Example webhook handler for Slack integration
app.post('/manus-webhook', (req, res) => {
  const { event_type, task_detail } = req.body;
  const { task_title, message, stop_reason } = task_detail || {};

  if (event_type === 'task_stopped' && stop_reason === 'finish') {
    // Post completion message to Slack
    slack.chat.postMessage({
      channel: '#ai-tasks',
      text: `✅ Task completed: ${task_title}\n${message}`
    });
  }

  res.status(200).send('OK');
});

Custom Dashboard Updates

Update your internal dashboards in real-time:

# Example webhook handler in Python/Flask
@app.route('/manus-webhook', methods=['POST'])
def handle_webhook():
    data = request.json
    event_type = data.get('event_type')
    task_detail = data.get('task_detail', {})

    # Update task status in your database
    if event_type == 'task_stopped':
        update_task_status(
            task_id=task_detail.get('task_id'),
            status='completed' if task_detail.get('stop_reason') == 'finish' else 'waiting',
            message=task_detail.get('message')
        )

    return '', 200

Troubleshooting

Common Issues

Webhook not receiving events: Verify your URL is accessible and returns 200 status
SSL/TLS errors: Ensure your endpoint uses valid HTTPS certificates
Timeout errors: Make sure your endpoint responds within 10 seconds

Testing Your Webhook

You can test your webhook endpoint using tools like:

webhook.site for quick testing
ngrok for local development
Postman or curl for manual testing

Getting Started

API Reference

Overview

Overview

How Webhook Events Work

Setting Up Webhooks

Manage Webhooks

Event Types and Payloads

`task_created` Event

`task_stopped` Event

Integration Examples

Slack Integration

Custom Dashboard Updates

Troubleshooting

Common Issues

Testing Your Webhook

​Overview

​How Webhook Events Work

​Setting Up Webhooks

Manage Webhooks

​Event Types and Payloads

​task_created Event

​task_stopped Event

​Integration Examples

​Slack Integration

​Custom Dashboard Updates

​Troubleshooting

​Common Issues

​Testing Your Webhook

Overview

How Webhook Events Work

Setting Up Webhooks

Event Types and Payloads

`task_created` Event

`task_stopped` Event

Integration Examples

Slack Integration

Custom Dashboard Updates

Troubleshooting

Common Issues

Testing Your Webhook