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

# Get notified by your agent

> Get notified in Slack, Teams, your browser, or by webhook when your agent finishes, fails, or has a question for you, so you can start a long job and walk away.

Your agent often runs for many minutes: scraping a list, working through a multi-step job, or waiting for you to answer a question. You should not have to keep the chat open to find out when it is done.

## Slack, Teams, and browser notifications

Open **Notifications** in the dashboard to choose what you hear about and where:

* **Notifications in Mobilerun** lists the moments you can be notified about. Use the quick presets to switch whole groups on or off.
* **Browser notifications** show a system notification even when Mobilerun is in the background. Your browser asks for permission the first time; on a phone, Mobilerun has to be added to your home screen and opened from there.
* **Notifications in Slack or Teams** sends the same moments to a channel. Pick the channel and what you want to hear about; you can change it later on the Notifications page. Questions your agent asks can also be answered from Slack.

Everything below is the webhook route, for sending these events to your own systems.

## Webhook events

Three webhook events cover the whole lifecycle of an agent turn. They fire for every conversation in your organization, whether the tab is open, in the background, or closed.

| Event | When it fires |
| - | - |
| `chat.turn.completed` | Your agent finished the current turn successfully. |
| `chat.turn.failed` | The turn ended with an error, including a crash your agent recovered from. |
| `chat.input.required` | Your agent asked you a question and is waiting for an answer. Approval cards do not fire this event. |

## Option A: let your agent set it up

Your agent can configure its own notifications. Start a conversation and say, in your own words:

> Notify me at [https://hooks.example.com/mobilerun](https://hooks.example.com/mobilerun) when you finish, fail, or need something from me. Use sensible settings and send a test.

Your agent will:

1. show you which notification events exist and confirm the selection,
2. create the webhook endpoint for that URL, filtered to exactly those events,
3. show you the signing secret **once** and ask you to store it,
4. send a test delivery and confirm it arrived.

Later you can ask it to change the events, re-enable a blocked endpoint, rotate the secret, or look up why a delivery failed.

> [!NOTE]
>
> Your agent creates generic signed webhooks. It does not send email or Slack messages itself; for Slack or Teams, use the Notifications page above. Point a webhook at an automation tool (n8n, Zapier, Make) or your own receiver to turn the event into any other message. A routine's **Notify on success** and **Notify on failure** controls live in the routine's Notifications dialog.

## Option B: set it up yourself

1. Open **Webhooks** in the dashboard and click **New webhook**.
2. Enter your HTTPS URL.
3. Select `chat.turn.completed`, `chat.turn.failed`, and `chat.input.required`.
4. Save and store the secret shown once.
5. Click **Send test event** and check that your receiver logged a `webhook.test` event.

Everything about signing, retries, and headers is the same as for any other webhook; see [Webhooks](https://docs.mobilerun.ai/webhooks.md).

## What the payload contains

The payloads are deliberately minimal. They identify the conversation and the turn, but never include your prompt, your agent's reply, or the text of a question. Open the conversation to read those.

### `chat.turn.completed` and `chat.turn.failed`

```json theme={null}
{
  "schemaVersion": 1,
  "id": "…",
  "source": "agents-api",
  "type": "chat.turn.completed",
  "ownerId": "…",
  "userId": "…",
  "createdBy": "…",
  "occurredAt": "2026-09-04T10:52:13.412Z",
  "data": {
    "sessionId": "d0d4a3f5-…",
    "turnId": "6b3f2c1e-…",
    "durationMs": 754210,
    "settleReason": "completed",
    "trigger": "chat"
  }
}
```

| Field | Description |
| - | - |
| `sessionId` | The conversation. Open it at `https://cloud.mobilerun.ai/c/{sessionId}`. |
| `turnId` | The turn that just ended. |
| `durationMs` | How long the turn ran. |
| `settleReason` | `completed` on `chat.turn.completed`, `error` on `chat.turn.failed`. |
| `trigger` | Always `chat`. |

You get exactly one terminal event per turn. No terminal event is sent when you stop the turn yourself, or when the turn belongs to a routine rather than an interactive conversation; those cases are visible in the chat only. A turn that stops because you ran out of credits does send `chat.turn.failed`.

### `chat.input.required`

```json theme={null}
{
  "type": "chat.input.required",
  "data": {
    "sessionId": "d0d4a3f5-…",
    "turnId": "6b3f2c1e-…",
    "questionId": "q_01J…",
    "questionCount": 1,
    "trigger": "chat"
  }
}
```

| Field | Description |
| - | - |
| `questionId` | Identifies the pending question. |
| `questionCount` | How many questions are open in this turn. |

The event is sent once per question. If you answer within the first seconds, before the event has been dispatched, it may be skipped.

## Turning it into a message

> [card] Slack or Teams
>
> Use the Notifications page, no webhook needed. For custom messages, use n8n's Webhook trigger, then a Slack node that posts `type`, `settleReason`, and a link built from `sessionId`.

> [card] Email via Zapier or Make
>
> Catch Hook → Email. Use one Zap per event type or branch on `type`.

> [card] Push notification
>
> Forward to a service such as ntfy or Pushover from your receiver.

> [card] [Your own receiver](https://docs.mobilerun.ai/webhooks.md#verifying-the-signature)
>
> Verify the signature, deduplicate on `id`, and act on `type`.

A minimal receiver that forwards to Slack:

```typescript TypeScript theme={null}
import express from 'express';
import { WebhookVerificationError, verifyWebhook } from '@mobilerun/sdk';

const app = express();
const slackWebhook = 'https://hooks.slack.com/services/…';
const text: Record<string, string> = {
  'chat.turn.completed': '✅ Your agent finished',
  'chat.turn.failed': '❌ Your agent failed',
  'chat.input.required': '❓ Your agent needs your answer',
};

// Register before any JSON middleware: verification needs the exact raw bytes.
app.post('/mobilerun', express.raw({ type: 'application/json' }), async (req, res) => {
  let event: { type: string; data: { sessionId: string } };
  try {
    event = await verifyWebhook({
      body: req.body, headers: req.headers, secret: process.env.WEBHOOK_SECRET!,
    }) as typeof event;
  } catch (error) {
    if (error instanceof WebhookVerificationError) { res.sendStatus(400); return; }
    throw error;
  }
  if (text[event.type]) {
    const link = `https://cloud.mobilerun.ai/c/${event.data.sessionId}`;
    await fetch(slackWebhook, {
      method: 'POST', headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ text: `${text[event.type]}: ${link}` }),
      signal: AbortSignal.timeout(5000),
    });
  }
  res.status(200).end();
});
app.listen(8000, '127.0.0.1');
```

```python Python theme={null}
import os

import requests
from flask import Flask, request
from mobilerun_sdk import WebhookVerificationError, verify_webhook

app = Flask(__name__)
SLACK_WEBHOOK = "https://hooks.slack.com/services/…"
TEXT = {
    "chat.turn.completed": "✅ Your agent finished",
    "chat.turn.failed": "❌ Your agent failed",
    "chat.input.required": "❓ Your agent needs your answer",
}

@app.route("/mobilerun", methods=["POST"])
def mobilerun():
    try:
        event = verify_webhook(request.get_data(), request.headers, os.environ["WEBHOOK_SECRET"])
    except WebhookVerificationError:
        return "", 400

    text = TEXT.get(event["type"])
    if text:
        link = f"https://cloud.mobilerun.ai/c/{event['data']['sessionId']}"
        requests.post(SLACK_WEBHOOK, json={"text": f"{text}: {link}"}, timeout=5)
    return "", 200
```


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