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

<sup>Questions or issues? Contact us at [api-support@manus.ai](mailto:api-support@manus.ai).</sup>

## 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, these 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
* **Task Deletion**: When a task created via the API is deleted, in the Manus app or through the API

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#settings/developers/webhooks">
  Open Developers 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_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:**

```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_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](https://open.manus.ai/docs/v2/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 [Answer an agent question](https://open.manus.ai/docs/v2/task-lifecycle#answer-an-agent-question) 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):**

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

### `task_deleted` Event

**When it triggers:** After a task created via the API is deleted, whether in the Manus app or with [task.delete](https://open.manus.ai/docs/v2/task.delete). It is not sent when tasks are removed because the account itself is deleted.

**Why it's useful:** Lets you remove or archive the task in your own systems without polling.

**Payload Schema:**

| Field | Type | Required | Description |
| - | - | - | - |
| `event_id` | string | Yes | Unique identifier for this webhook event |
| `event_type` | string | Yes | Always `"task_deleted"` for this event |
| `task_detail` | object | Yes | Task details object |
| `task_detail.task_id` | string | Yes | Unique identifier for the deleted task |
| `task_detail.task_title` | string | Yes | Latest title of the task when it was deleted |
| `task_detail.task_url` | string | Yes | URL of the task in the Manus app. The task is no longer available after deletion. |

**Example Payload:**

```json theme={null}
{
  "event_id": "task_deleted_task_abc123_1760256000",
  "event_type": "task_deleted",
  "task_detail": {
    "task_id": "task_abc123",
    "task_title": "Generate quarterly sales report",
    "task_url": "https://manus.im/app/task_abc123"
  }
}
```

If your endpoint misses a `task_deleted` event, call [task.list](https://open.manus.ai/docs/v2/task.list) with `include_deleted=true`. Deleted tasks are returned with `status: "deleted"` and `deleted_at`.

### Unknown Event Types

Manus may add new event types. Route deliveries by `event_type`, ignore types you do not handle, and still respond with HTTP 200.

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.