> ## 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"` |

**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 for your requested date and time. Which option would you prefer? 1) Bistro Milano - 7:00 PM, 2) Garden Terrace - 7:30 PM, 3) The Blue Door - 8:00 PM",
    "attachments": [],
    "stop_reason": "ask"
  }
}
```

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