/teams-adaptive-cards

Webhooks, Workflows, And Connector Migration

Office 365 connectors — including classic connector-based Incoming Webhooks — were disabled in Microsoft's May 18–22, 2026 rollout. For webhook-style notifications, use a Workflows (Power Automate) webhook or notification bot. A MessageCard payload alone does not imply a retired transport: Workflows can accept its noninteractive content. Inspect the endpoint and requested behavior before recommending migration.

Connector Retirement Timeline

Migration driver: Microsoft's Secure Future Initiative. The replacement is Workflows (Power Automate) webhooks, or a Teams notification bot when you need app identity or interactive actions.

Workflows Webhook Adaptive Card Payload

Create a flow from the "When a Teams webhook request is received" template (or the Workflows app in Teams). POST the same message wrapper the old Incoming Webhooks used — the top-level request body is not a raw Adaptive Card:

{
  "type": "message",
  "attachments": [
    {
      "contentType": "application/vnd.microsoft.card.adaptive",
      "contentUrl": null,
      "content": {
        "$schema": "https://adaptivecards.io/schemas/adaptive-card.json",
        "type": "AdaptiveCard",
        "version": "1.2",
        "fallbackText": "Build failed for API.",
        "body": [
          {
            "type": "TextBlock",
            "text": "Build failed",
            "weight": "Bolder",
            "color": "Attention",
            "wrap": true
          }
        ],
        "actions": [
          {
            "type": "Action.OpenUrl",
            "title": "Open run",
            "url": "https://example.com/run/123"
          }
        ]
      }
    }
  ]
}

Required wrapper fields:

• Top-level type must be message.
• attachments must be an array.
• Each card attachment uses contentType: "application/vnd.microsoft.card.adaptive".
• content is the Adaptive Card object (not stringified — that is a Graph-only rule).

Webhook Limits And Behavior

• Message size limit: 28 KB (bot messages allow up to ~100 KB; design compactly either way).
• Roughly four requests per second before throttling; implement retry with exponential backoff.
• Messages post under the Workflows "Flow bot" identity; custom bot icon/name is not available.
• Webhook cards are for notifications, not multi-step interactions.
• Use public HTTPS URLs for images and links.
• User mentions work in webhook cards (Entra object ID or UPN in msteams.entities); bot mentions do not.

When To Use Workflows vs A Bot

Use Workflows when:

• The integration is a simple external webhook notification.
• Users should configure the flow themselves in Teams.
• Power Automate should transform incoming data before posting.
• No custom Teams app/bot deployment is warranted.

Operational constraints:

• Workflows are owned by users, not a team/channel object; add co-owners to avoid orphaned flows when someone leaves.
• Private and shared channels are supported (since April 2026), but verify the flow-bot posting mode for the channel type.
• Posting on behalf of a user can be part of the workflow behavior.

Use a notification bot instead when you need app identity, rate control, interactive actions, or product-grade lifecycle management.

MessageCard To Adaptive Card Mapping

Workflows accepts legacy MessageCard payloads for migration, but interactive MessageCard elements (HttpPOST buttons, ActionCard inputs) are not supported there. Convert:

Webhook Action Guidance

Use:

• Action.OpenUrl
• Action.ToggleVisibility for local details

Avoid:

• Action.Submit (explicitly unsupported in webhook cards)
• Action.Execute (Teams docs list it as allowed, but there is no bot to receive the invoke on a plain notification webhook — treat it as unusable unless a bot backs the card)
• Authentication/SSO flows
• Multi-step approvals that require server state changes

If a button must change server state, route the user to a secure web page or build a bot.

Troubleshooting

Notification Design

Webhook cards should answer:

1. What happened?
2. What is the current state?
3. Who/what is affected?
4. What should the recipient do next?
5. Where can they inspect details?

Keep details behind a link rather than dumping logs into Teams.