> ## Documentation Index
> Fetch the complete documentation index at: https://open.manus.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Real-time notifications for task lifecycle events

<Warning>
  **API v1 is deprecated and will be removed in the future.** Please migrate to [API v2](https://open.manus.ai/docs/v2/introduction) for new features and long-term support.
</Warning>

## Overview

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

<Card title="Manage Webhooks" horizontal arrow icon="wrench" href="https://manus.im/app?show_settings=integrations&app_name=api">
  Navigate to the API Integration settings to create or manage webhooks.
</Card>

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_id`    | string | Yes      | Unique identifier for the created task   |
| `task_title` | string | Yes      | Human-readable title of the task         |
| `task_url`   | string | Yes      | Direct URL to view the task in Manus app |

**Example Payload:**

```json theme={null}
{
  "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_id`              | string | Yes      | Unique identifier for the task                                                                                                                                                                                            |
| `task_title`           | string | Yes      | Human-readable title of the task                                                                                                                                                                                          |
| `task_url`             | string | Yes      | Direct URL to view the task in Manus app                                                                                                                                                                                  |
| `message`              | string | Yes      | Status message from the task execution                                                                                                                                                                                    |
| `attachments`          | array  | No       | List of files generated by the task                                                                                                                                                                                       |
| `stop_reason`          | string | Yes      | Why the task stopped: `"finish"` or `"ask"`                                                                                                                                                                               |
| `question_expectation` | object | No       | Question metadata for `stop_reason: "ask"`: `event_id`, `options`, `selection_mode`, and `response_method: "send_message"`. In v1, reply with `POST /v1/tasks`, setting `taskId` to this task and `prompt` to the answer. |

**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):**

```json theme={null}
{
  "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):**

```json theme={null}
{
  "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"
    }
  }
}
```

`question_expectation.event_id` identifies the underlying question event, not the webhook notification identified by the top-level `event_id`. This nested ID is webhook-only (v2 message lists use the enclosing message's `id`); it is neither required for a reply nor an idempotency key.

`options` contains candidate display text. Use `selection_mode` (`single` or `multiple`) as a UI hint, not as an enforced answer schema. Users may reply with their own text. For multiple selections, combine the selected text into one readable `prompt`; no delimiter or option-ID array is required. For free-text questions, `options` is `[]`; `single` is the default mode, not a restriction on the text.

The fixed `response_method: "send_message"` means an ordinary conversational reply. **In v1 this maps to `POST /v1/tasks`**, not a separate message endpoint. For example, reply with:

```json theme={null}
{
  "taskId": "task_abc123",
  "prompt": "Bistro Milano, please.",
  "agentProfile": "manus-1.6"
}
```

Send a non-empty answer. If a client encounters an unknown response method, stop automatic dispatch and check the current documentation.

## Integration Examples

### Slack Integration

Post task updates directly to Slack channels:

```javascript theme={null}
// 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:

```python theme={null}
# 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](https://webhook.site) for quick testing
* [ngrok](https://ngrok.com) for local development
* Postman or curl for manual testing