Microsoft Teams Webhooks

Use this guide to send endpoint traffic to a Microsoft Teams channel.

Purpose#

Use this guide to:

• Create a Teams incoming webhook URL.
• Save Microsoft Teams as a relay target.
• Attach the target to an endpoint destination.
• Test delivery.

Before you start#

• A Microsoft Teams account with access to Workflows or Power Automate, or permission to manage a legacy channel connector.
• Access to Relay targets and Endpoints in PayloadRelay.

Payload format#

PayloadRelay sends a Teams delivery as a MessageCard JSON envelope. This envelope operates with a legacy Incoming Webhook connector URL and with the Teams workflow webhook trigger. For Workflows, configure the next step to post the received message or card in the Teams chat or channel.

{
  "@type": "MessageCard",
  "@context": "https://schema.org/extensions",
  "themeColor": "0078D4",
  "summary": "PayloadRelay webhook event",
  "title": "PayloadRelay webhook event",
  "text": "```json\n{ ...original payload... }\n```"
}

Microsoft gives a Teams webhook message size limit of 28 KB. PayloadRelay examines the final JSON body before the delivery. If the Teams message is larger than the limit, PayloadRelay does not send it, and it records a failed delivery in Activity with this reason:

Microsoft Teams message exceeds the supported 28 KB limit.

Teams MessageCard text supports basic Markdown. Teams shows HTML markup as plain text. PayloadRelay does not use HTML tags for the Teams formatting.

When a message template contains the View in PayloadRelay link, PayloadRelay sends it as a MessageCard OpenUri action. A legacy Incoming Webhook connector card shows this action as a button. Teams Workflows can accept the action in the request body and ignore the button when it posts the message.

Procedure#

1. Create a webhook URL in Teams#

Option A: Workflows or Power Automate

1. In Teams, select Workflows in the Apps section, or open Power Automate directly.
2. Create a new flow with the trigger When a Teams webhook request is received.
3. Add a Teams action that posts the received message or card to the chat or channel.
4. Copy the HTTP POST URL from the trigger step.

Microsoft states that the Microsoft 365 Connectors are near to their end of life. For a new webhook integration, use Workflows.

Option B: Incoming Webhook connector (legacy)

1. In the Teams channel, open the channel menu and select Connectors.
2. Search for Incoming Webhook and select Configure.
3. Give the connector a name, such as PayloadRelay. You can also upload an icon. Select Create.
4. Copy the webhook URL (https://<tenant>.webhook.office.com/webhookb2/...).
5. Select Done.

2. Add a Microsoft Teams relay target#

1. Open Relay targets in PayloadRelay.
2. Select Add target.
3. Select Microsoft Teams as the type.
4. Paste the webhook URL into the Microsoft Teams webhook URL field.
   • The accepted hosts are *.webhook.office.com and *.logic.azure.com (Power Automate).
5. Add a name and a description. These values are optional. Then save.

The target needs no email confirmation. It is available immediately.

3. Attach the target to an endpoint#

1. Open the endpoint create page or the endpoint edit page.
2. In Outputs, select the Microsoft Teams target.
3. Save the endpoint.

4. Test delivery#

1. On the Relay targets page, find the Teams target and select Send test.
2. PayloadRelay sends a test MessageCard to the channel.
3. Make sure that the message appears in Teams.

Retry behavior#

A failed delivery uses the standard automatic retry schedule of PayloadRelay, in the limit of the plan. Microsoft Teams can rate-limit a continuous burst. Send the deliveries less frequently, or let the retries correct the temporary errors.

PayloadRelay does not retry a message that is larger than the Teams 28 KB limit, because Teams rejects the message until it is smaller. Use a shorter message template, or add routing rules or transformation rules that make the data for Teams smaller.

Troubleshooting#

Microsoft references#

• Create Incoming Webhooks
• Microsoft Teams connector and webhook trigger