---
updatedAt: 2025-12-10T18:17:50.000Z
agentTools:
  projectIndex: https://docs.query.ai/llms.txt
---

# Microsoft Teams Destination Setup

Send detection alerts to Microsoft Teams channels with rich formatted messages using Adaptive Cards.

# Microsoft Teams Destination Setup

Send detection alerts to Microsoft Teams channels with rich formatted messages using Adaptive Cards.

## Prerequisites

* Microsoft Teams workspace
* Admin access to create Incoming Webhooks
* Target channel created

## Setup Steps

### 1. Create Incoming Webhook

In Microsoft Teams:

1. Navigate to the target channel
2. Click the **...** (More options) next to the channel name
3. Select **Connectors** (or **Workflows** in newer Teams)
4. Search for **Incoming Webhook**
5. Click **Add** or **Configure**
6. Enter a name (e.g., "Query.ai Security Detections")
7. Optionally upload an image
8. Click **Create**
9. **Copy the webhook URL** - you'll need this for configuration

**Important**: Save the webhook URL securely. It cannot be retrieved later.

### 2. Configure in Query.ai

Contact your Query.ai administrator to configure the Microsoft Teams destination with:

**Required Configuration**:

* Webhook URL (stored securely)

**Optional Configuration**:

* Timeout in seconds (default: 30)

## Message Format

Teams alerts are sent as Adaptive Cards with:

### Header

* Severity emoji and color
* Detection name

### Details Section

* **Outcome**: MATCHED or ERROR
* **Severity**: Detection severity level
* **Matches**: Number of matching events
* **Detection ID**: Configuration ID
* **Run Type**: SCHEDULED or MANUAL
* **Threshold**: Operator and value
* **Eagerness**: EAGER or EXHAUSTIVE

### Description

Full detection description text

### Timestamps

* **Ran At**: When detection executed
* **Time Range**: Query time window
* **Exhaustiveness**: COMPLETED or STOPPED\_EARLY (if available)
* **Search ID**: FSQL API identifier (if available)
* **Trace ID**: AWS X-Ray trace ID (if available)

### Errors

List of error messages (if any)

### Action Button

"View in Query.ai" button linking to replay

### Color Coding

Card accent color based on severity:

* Red: CRITICAL
* Orange: HIGH
* Yellow: MEDIUM
* Green: LOW

## Testing

Test webhook with curl:

```bash
curl -X POST "https://your-tenant.webhook.office.com/webhookb2/..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "message",
    "attachments": [
      {
        "contentType": "application/vnd.microsoft.card.adaptive",
        "content": {
          "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
          "type": "AdaptiveCard",
          "version": "1.4",
          "body": [
            {
              "type": "TextBlock",
              "text": "Test Alert from Query.ai",
              "weight": "bolder",
              "size": "large"
            }
          ]
        }
      }
    ]
  }'
```

**Expected Response**: `1` (success)

## Troubleshooting

| Error                  | Solution                                         |
| ---------------------- | ------------------------------------------------ |
| `400 Bad Request`      | Verify webhook URL is correct and complete       |
| `404 Not Found`        | Webhook may have been deleted, recreate in Teams |
| `401 Unauthorized`     | Webhook URL is invalid                           |
| Messages not appearing | Check channel, verify webhook is active          |

## Configuration Options

### Required

**webhook\_url** (secret)

* Microsoft Teams Incoming Webhook URL
* Format: `https://your-tenant.webhook.office.com/webhookb2/...`
* Stored securely in AWS Secrets Manager

### Optional

**timeout**

* Request timeout in seconds
* Default: 30
* Maximum: 300 (5 minutes)

## Webhook Management

### View Configured Webhooks

1. Navigate to channel in Teams
2. Click **...** (More options)
3. Select **Connectors** or **Workflows**
4. View **Configured** tab
5. See list of active webhooks

### Remove Webhook

1. Navigate to configured webhooks
2. Find the webhook
3. Click **Remove**
4. Confirm removal

**Note**: Removing webhook will break alert delivery. Update Query.ai configuration if webhook is removed.

### Webhook Limitations

* Maximum 1 MB message size
* Rate limit: 4 requests per second per webhook
* Webhook URLs expire if unused for 90 days

## Security Best Practices

1. **Never Commit Webhook URLs**: Always store in Secrets Manager
2. **Treat as Secrets**: Webhook URLs provide unauthenticated access
3. **Rotate Regularly**: Recreate webhooks every 90 days
4. **Monitor Usage**: Review channel for unexpected messages
5. **Limit Distribution**: Don't share webhook URLs

## Webhook Rotation

To rotate webhook URL:

1. Create new Incoming Webhook in Teams
2. Copy new webhook URL
3. Update URL in Query.ai configuration
4. Test with a manual detection run
5. Remove old webhook from Teams

## Multiple Channels

Create separate destinations for different Teams channels:

**Example Use Cases**:

* Critical alerts → #security-critical channel
* All alerts → #security-all channel
* Team-specific → Team-specific channels

Each destination uses a different webhook URL from different channels.

## Adaptive Cards

Teams uses Adaptive Cards for rich formatting. The detection alerts use:

* **TextBlock**: For text content
* **FactSet**: For key-value pairs (details)
* **ActionSet**: For buttons
* **Container**: For grouping elements

Learn more: [Adaptive Cards Designer](https://adaptivecards.io/designer/)

## Resources

* [Microsoft Teams Incoming Webhooks](https://learn.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook)
* [Adaptive Cards Documentation](https://adaptivecards.io/)
* [Teams Connectors](https://learn.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/what-are-webhooks-and-connectors)