Microsoft Teams trigger

Overview

Receives webhook notifications from Microsoft Graph change notifications when events occur in Microsoft Teams. Supports triggering on new channel messages, new chat messages, new channels, new chats, and new team members. Microsoft Graph uses a subscription-based webhook model: subscriptions are created via the Graph API with a notificationUrl pointing to this webhook endpoint. When the subscription is first created, Microsoft sends a validation request with a validationToken query parameter that must be echoed back as plain text. Subsequent notifications arrive as POST requests with an array of change notification objects in the body. Each notification includes the resource path, subscription ID, tenant ID, and resource data. Supports scoping to specific teams, channels, or chats, or watching all available resources. Requires OAuth2 authentication with appropriate Microsoft Graph permissions (ChannelMessage.Read.All, Chat.Read.All, Team.ReadBasic.All, Subscription.ReadWrite.All). Useful for building chat bots, team activity monitors, notification pipelines, and collaboration automation workflows.

Node Type

Trigger — webhook (receives incoming HTTP callbacks)

Input / Output

Direction	Port(s)
Input	None (trigger node)
Output	Output

Credentials

This tool requires Microsoft Teams OAuth2 credentials. See the Credentials Guide for setup instructions.

Parameters

Parameter	Type	Required	Default	Description
Microsoft Account	credential	No	—	Connect your Microsoft account via OAuth2.
Trigger On	options	No	newChannelMessage	Select the event to trigger the workflow.
				Options: newChannel (a new channel is created), newChannelMessage (a message is posted to a channel), newChat (a new chat is created), newChatMessage (a message is posted to a chat), newTeamMember (a new member is added to a team)
Watch All Teams	boolean	No	false	Whether to watch for the event in all the available teams. (shown when Trigger On is newChannel, newChannelMessage, newTeamMember)
Team ID	string	Yes	—	The ID of the team to watch. Enter a Team ID (UUID format, e.g. 61165b04-e4cc-4026-b43f-926b4e2a7182) or extract from a Teams URL. (shown when Trigger On is newChannel, newChannelMessage, newTeamMember and Watch All Teams is false)
Watch All Channels	boolean	No	false	Whether to watch for the event in all the available channels. (shown when Trigger On is newChannelMessage and Watch All Teams is false)
Channel ID	string	Yes	—	The ID of the channel to watch. Enter a Channel ID (e.g. 19:-xlxyqXNSCxpI1SDzgQ_L9ZvzSR26pgphq1BJ9y7QJE1@thread.tacv2). (shown when Trigger On is newChannelMessage, Watch All Teams is false and Watch All Channels is false)
Watch All Chats	boolean	No	false	Whether to watch for the event in all the available chats. (shown when Trigger On is newChatMessage)
Chat ID	string	Yes	—	The ID of the chat to watch. Enter a Chat ID (e.g. 19:7e2f1174-e8ee-4859-b8b1-a8d1cc63d276@unq.gbl.spaces). (shown when Trigger On is newChatMessage and Watch All Chats is false)

Output Data

Microsoft Graph delivers an array of change notifications, and each notification becomes its own output item:

• _trigger — always microsoft_teams_webhook
• _timestamp — ISO 8601 timestamp of when the request arrived
• _webhookEvent — the notification’s change type (created)
• subscriptionId — the Graph subscription that produced the notification
• resource — the Graph resource path the change happened on, e.g. teams/{teamId}/channels/{channelId}/messages/{messageId}
• tenantId — the Microsoft 365 tenant the change came from
• clientState — the client state value carried on the subscription
• subscriptionExpirationDateTime — when the subscription expires
• changeType — the change type Graph reported
• resourceData — the changed resource stub, with id, @odata.type and @odata.id plus any additional fields Graph includes

Reference the payload downstream by expression, e.g. {{ $json.resourceData.id }}. Change notifications identify what changed rather than carrying the full message body, so follow this trigger with a Microsoft Graph read step when you need the message content. Graph’s validation handshake is answered automatically and produces no items.

Example Configuration

Watch every team for new channels:

{
  "type": "microsoft_teams_trigger",
  "parameters": {
    "event": "newChannel",
    "watchAllTeams": true
  }
}

Watch one team for new members:

{
  "type": "microsoft_teams_trigger",
  "parameters": {
    "event": "newTeamMember",
    "watchAllTeams": false,
    "teamId": "61165b04-e4cc-4026-b43f-926b4e2a7182"
  }
}

Watch every channel in one team for messages:

{
  "type": "microsoft_teams_trigger",
  "parameters": {
    "event": "newChannelMessage",
    "watchAllTeams": false,
    "teamId": "61165b04-e4cc-4026-b43f-926b4e2a7182",
    "watchAllChannels": true
  }
}

Watch a single channel for messages:

{
  "type": "microsoft_teams_trigger",
  "parameters": {
    "event": "newChannelMessage",
    "watchAllTeams": false,
    "teamId": "61165b04-e4cc-4026-b43f-926b4e2a7182",
    "watchAllChannels": false,
    "channelId": "19:-xlxyqXNSCxpI1SDzgQ_L9ZvzSR26pgphq1BJ9y7QJE1@thread.tacv2"
  }
}

Watch every chat for messages:

{
  "type": "microsoft_teams_trigger",
  "parameters": {
    "event": "newChatMessage",
    "watchAllChats": true
  }
}

Watch one specific chat:

{
  "type": "microsoft_teams_trigger",
  "parameters": {
    "event": "newChatMessage",
    "watchAllChats": false,
    "chatId": "19:7e2f1174-e8ee-4859-b8b1-a8d1cc63d276@unq.gbl.spaces"
  }
}

Fire when a new chat is created:

{
  "type": "microsoft_teams_trigger",
  "parameters": {
    "event": "newChat"
  }
}

Trigger Behavior

• Activation: When the workflow is activated, a webhook endpoint is registered with the service.
• Deactivation: The webhook is automatically unregistered when the workflow is deactivated.
• Payload: The incoming webhook payload is parsed and output as workflow items.
• Verification: Supports signature verification where applicable.

Tips

This tool detects events in Microsoft Teams, such as new messages, channels, chats, or team member additions. It is ideal for starting workflows based on specific Teams activities rather than sending messages or retrieving information. It produces a trigger signal when a configured Teams event occurs.

Important Notes

• ID Formats: Team IDs use UUID format, while Channel IDs and Chat IDs use Microsoft’s thread-based format
• Conditional Logic: Parameters are shown/hidden based on event selection and previous parameter values
• Scope Hierarchy: The configuration follows a hierarchical scope: All Teams → Specific Team → All Channels → Specific Channel
• Event Dependencies: Some parameters only apply to specific events - ensure the event selection matches the desired monitoring scope