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:

Navigate to the target channel
Click the ... (More options) next to the channel name
Select Connectors (or Workflows in newer Teams)
Search for Incoming Webhook
Click Add or Configure
Enter a name (e.g., "Query.ai Security Detections")
Optionally upload an image
Click Create
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:

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

Navigate to channel in Teams
Click ... (More options)
Select Connectors or Workflows
View Configured tab
See list of active webhooks

Remove Webhook

Navigate to configured webhooks
Find the webhook
Click Remove
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

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

Webhook Rotation

To rotate webhook URL:

Create new Incoming Webhook in Teams
Copy new webhook URL
Update URL in Query.ai configuration
Test with a manual detection run
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