Notifications - Mapping API Docs

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

Setup
Payload

In Slack, Apps → Incoming Webhooks → Add Configuration.
Pick the channel, click Add Incoming WebHooks integration.
Copy the webhook URL (https://hooks.slack.com/services/T.../B.../...).
In the agent UI, Channels → Add → Slack, paste the URL, pick subscriptions.
Click Test — a sample message lands in the Slack channel.

Slack-formatted Block Kit:

{
  "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>"
      }
    }
  ]
}

Generic HTTPS webhook

Send a POST to your own endpoint. Auth via Bearer, HMAC-SHA256, or Basic — same scheme as data sinks.

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

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

Agents overview — channels are part of the trust loop.
Recipes: Daily coverage report to Slack
Cost and limits — the 80% warning fires on on_cost_threshold.

​Subscriptions

​Email

​Slack webhook

​Generic HTTPS webhook

​Test endpoint

​Related

Subscriptions

Email

Slack webhook

Generic HTTPS webhook

Test endpoint

Related