> ## 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
Questions or issues? Contact us at [api-support@manus.ai](mailto:api-support@manus.ai).
## 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
Navigate to the API Integration 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:**
```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.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. |
**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