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

# Webhooks

> Receive real-time notifications when task events occur in your Mobilerun account.

The Webhooks tab allows you to configure HTTP callbacks that notify your systems when events occur. Use webhooks to integrate Mobilerun with your existing infrastructure and automation pipelines.

## What is a Webhook?

A webhook is an HTTP request that Mobilerun sends to your server when a specific event happens. Instead of polling the API to check for updates, your server receives notifications automatically in real-time.

When an event occurs:

1. Mobilerun detects the event (e.g., a task completes)
2. Mobilerun sends an HTTP POST request to your configured URL
3. Your server receives the payload and processes it

This enables real-time integrations without constant API polling.

## Event Triggers

Configure webhooks to fire on any of these task events:

| Event         | Description                              |
| ------------- | ---------------------------------------- |
| **created**   | A new task has been submitted            |
| **running**   | A task has started executing on a device |
| **paused**    | A task execution has been paused         |
| **completed** | A task finished successfully             |
| **failed**    | A task encountered an error and stopped  |
| **cancelled** | A task was manually cancelled            |

<Info>
  You can subscribe to multiple events with a single webhook, or create separate webhooks for different event types.
</Info>

## Creating a Webhook

To add a new webhook:

1. Click **Add Webhook**
2. Enter your endpoint URL (must be HTTPS)
3. Select which events should trigger the webhook
4. Save the webhook

Your endpoint will start receiving events immediately.

## Webhook Payload

When an event fires, Mobilerun sends a POST request with a JSON payload containing:

```json theme={null}
{
  "event": "completed",
  "task": {
    "id": "task_abc123",
    "task": "Open Settings and enable dark mode",
    "status": "completed",
    "deviceId": "device_xyz",
    "createdAt": "2025-01-08T10:30:00Z",
    "finishedAt": "2025-01-08T10:32:45Z",
    "succeeded": true,
    "output": {}
  }
}
```

## Managing Webhooks

Your webhook list displays:

| Field       | Description                       |
| ----------- | --------------------------------- |
| **URL**     | The endpoint receiving events     |
| **Events**  | Which events trigger this webhook |
| **State**   | Active, disabled, or deleted      |
| **Created** | When the webhook was configured   |

### Webhook States

| State        | Description                                |
| ------------ | ------------------------------------------ |
| **Active**   | Webhook is receiving events normally       |
| **Disabled** | Webhook is paused and not receiving events |
| **Deleted**  | Webhook has been removed                   |

### Edit Webhooks

Update a webhook to change:

* The events it subscribes to
* Its active/disabled state

### Delete Webhooks

Remove webhooks that are no longer needed. Deleted webhooks stop receiving events immediately.

## Use Cases

<CardGroup cols={2}>
  <Card title="CI/CD Integration" icon="ellipsis">
    Trigger deployment pipelines when test tasks complete successfully.
  </Card>

  <Card title="Alerting" icon="bell">
    Send notifications to Slack or email when tasks fail.
  </Card>

  <Card title="Data Processing" icon="database">
    Store task results in your database automatically.
  </Card>

  <Card title="Workflow Automation" icon="workflow">
    Chain tasks together by starting new tasks when others complete.
  </Card>
</CardGroup>

## Integration Examples

### Zapier

Connect Mobilerun to thousands of apps using Zapier. Trigger Zaps when tasks complete and automate downstream workflows.

### n8n

Use webhooks to integrate with n8n workflows for custom automation logic.

### Custom Endpoints

Build your own webhook receiver to process events however you need:

```python theme={null}
from flask import Flask, request

app = Flask(__name__)

@app.route("/webhook", methods=["POST"])
def handle_webhook():
    payload = request.json
    event = payload["event"]
    task = payload["task"]
    
    if event == "completed" and task["succeeded"]:
        # Handle successful task
        pass
    elif event == "failed":
        # Handle failed task
        pass
    
    return "", 200
```

## Best Practices

| Practice              | Description                                              |
| --------------------- | -------------------------------------------------------- |
| **Use HTTPS**         | Always use secure endpoints for webhook URLs             |
| **Respond quickly**   | Return a 2xx status code promptly to acknowledge receipt |
| **Handle duplicates** | Design your handler to be idempotent in case of retries  |
| **Verify payloads**   | Validate incoming data before processing                 |