# Set up Microsoft Teams alerts

Microsoft Teams alerts are delivered through a **Workflow** that posts an Adaptive Card into a channel, using
Teams' current webhook mechanism. Under the hood a Teams contact is an `http` contact with its `gateway` set to
`Teams`.

:::caution[The old connector is retired]
Microsoft retired the legacy "Incoming Webhook" O365 connector. If you set up Teams alerts a long time ago using
that connector, it has stopped working - recreate the contact using a Workflow as below.
:::

## Settings reference

| Setting (UI label) | API field (v2) | Type / allowed values | Default | Plan limits | What it does for you |
|---|---|---|---|---|---|
| Contact Type | `type` | `"http"` | - | - | Teams is stored as a plain `http` contact |
| Gateway | `gateway` | `"Teams"` | - (must be set explicitly) | - | Formats the request as a Teams Adaptive Card instead of a plain webhook |
| Webhook URL | `address` | The Workflow's webhook URL | - (required) | - | Where the card posts |
| Group events | `groupedAlerts` | boolean | `false` | - | Combine simultaneous alerts into one card - see [grouped alerts](/alerts/grouped-alerts/) |

Unlike Slack, **the `gateway` value is the only way HostTracker recognizes a Teams contact** - there's no
address-pattern auto-detection, on purpose: a generic webhook can legitimately point at the same kind of
Power-Automate URL a Teams workflow uses, for reasons that have nothing to do with Teams, so guessing from the
address alone risked silently re-routing a working, unrelated webhook contact.

## Set it up in the app

1. In the Teams channel you want alerts in, add a **Workflow** built from the "When a Teams webhook request is
   received" trigger, ending in "Post to a channel" (or your organization's equivalent). Copy the webhook URL the
   workflow gives you.
2. In HostTracker, open **Contacts** and click **Add contact**.
3. Choose **Microsoft Teams**.
4. Paste the workflow's webhook URL and give the contact a name.
5. Save.

## What the message looks like

An Adaptive Card in the target channel: monitor name, status, and relevant detail fields laid out as a card
rather than plain text.

## Do it with the API or MCP

```
POST /contact
{ "type": "http", "gateway": "Teams", "address": "https://...", "name": "Ops Teams channel" }
```

MCP: use `api_request` with the body above - `create_contact` doesn't cover `http`/gateway contacts.

## What happens next

An `http` contact is born confirmed - there's no code to verify. [Send a test alert](/alerts/test-a-contact/)
to confirm the card actually renders in your channel.

## Limits and gotchas

- **Unlike Slack, HostTracker doesn't auto-detect a Teams URL from a generic webhook contact** - add it
  explicitly as a **Teams** contact (or send `gateway: "Teams"` on the API) so it's formatted as an Adaptive
  Card.
- Grouping is **off** by default. Turn on the contact's **Group events** toggle to combine simultaneous alerts
  into one card instead of posting them individually.
- A `gateway` value the API doesn't recognize is refused (`422 unknown_enum_value`) - use the exact spelling
  `Teams`.
- Being a **recognized gateway** also means Teams can receive certificate-expiry, domain-expiry, DNSBL
  blacklist and Web Risk notices - a plain unrecognized webhook contact cannot (see
  [Webhook](/alerts/channels/webhook/#limits-and-gotchas)).

## Related

- [Slack](/alerts/channels/slack/) - [Mattermost](/alerts/channels/mattermost/)
- [All channels](/alerts/channels/)