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

# Notifications

> Email, Slack, and generic webhook notifications for agent activity.

Agents can notify you (and your team) when something happens — an action was taken, a human escalation was filed, the agent paused, or the cost cap is approaching. v1 supports three channel types: **email**, **Slack incoming webhook**, and **generic HTTPS webhook**.

## Subscriptions

Each channel subscribes to a subset of event kinds:

| Event               | Fires when                                                                                            |
| ------------------- | ----------------------------------------------------------------------------------------------------- |
| `on_action`         | The agent took an autonomous mutating action (proposed match, filed pending item, mode change, etc.). |
| `on_escalation`     | A pending item was filed for human review.                                                            |
| `on_pause`          | The agent transitioned to `PAUSED_COST`, `PAUSED_RATE`, or `PAUSED_USER`.                             |
| `on_cost_threshold` | Daily spend crossed the `on_cost_threshold_pct` line (default 80%).                                   |

Set per-channel in the rule set or via `PATCH /api/v1/agents/{id}/channels/{cid}`.

## Email

| Field                | Required | Example                         |
| -------------------- | -------- | ------------------------------- |
| `type`               | yes      | `EMAIL`                         |
| `target`             | yes      | `ops@acme.com`                  |
| `eventSubscriptions` | yes      | `["on_escalation", "on_pause"]` |

Emails are sent from `agents@mapping.travel` (configurable per workspace at the org level). The subject line is the event kind + agent name; the body links back to the run or pending item.

## Slack webhook

<Tabs>
  <Tab title="Setup">
    1. In Slack, **Apps → Incoming Webhooks → Add Configuration**.
    2. Pick the channel, click **Add Incoming WebHooks integration**.
    3. Copy the webhook URL (`https://hooks.slack.com/services/T.../B.../...`).
    4. In the agent UI, **Channels → Add → Slack**, paste the URL, pick subscriptions.
    5. Click **Test** — a sample message lands in the Slack channel.
  </Tab>

  <Tab title="Payload">
    Slack-formatted Block Kit:

    ```json theme={null}
    {
      "blocks": [
        {
          "type": "header",
          "text": { "type": "plain_text", "text": "Agent: Booking.com hygiene" }
        },
        {
          "type": "section",
          "text": {
            "type": "mrkdwn",
            "text": "*Event:* `on_escalation`\n*Subject:* 12 unmatched rows need review\n<https://app.mapping.travel/agents/.../pending/...|Open in app>"
          }
        }
      ]
    }
    ```
  </Tab>
</Tabs>

## Generic HTTPS webhook

Send a `POST` to your own endpoint. Auth via Bearer, HMAC-SHA256, or Basic — same scheme as [data sinks](/agents/data-sources-and-sinks#outbound-pushing-results).

<CodeGroup>
  ```json Payload theme={null}
  {
    "agentId": "agt_01J...",
    "agentName": "Booking.com hygiene",
    "event": "on_escalation",
    "subject": "12 unmatched rows need review",
    "body": {
      "pendingItemId": "pi_01J...",
      "kind": "MATCH_PROPOSAL",
      "subject": "12 unmatched rows need review",
      "url": "https://app.mapping.travel/agents/.../pending/pi_01J..."
    },
    "timestamp": "2026-05-25T12:34:56Z"
  }
  ```

  ```bash HMAC verification (Node) theme={null}
  const crypto = require('crypto');
  const signature = req.headers['x-mt-signature'].replace('sha256=', '');
  const expected = crypto
    .createHmac('sha256', process.env.MT_WEBHOOK_SECRET)
    .update(req.rawBody)
    .digest('hex');
  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    return res.status(401).end();
  }
  ```
</CodeGroup>

## Test endpoint

`POST /api/v1/agents/{id}/channels/{cid}/test` sends a synthetic event of every subscribed kind. Returns the delivery result (status code, latency, body excerpt).

## Related

* [Agents overview](/agents/overview) — channels are part of the trust loop.
* [Recipes: Daily coverage report to Slack](/agents/recipes/daily-coverage-report-to-slack)
* [Cost and limits](/agents/cost-and-limits) — the 80% warning fires on `on_cost_threshold`.