Microsoft Teams: Incoming Webhook

On this page

You can post a card into a Microsoft Teams channel when a new Incident is created in Alloy Navigator. Alloy Navigator ships no ready-made Teams notification for this. You assemble it from two parts that you create yourself:

  • In Microsoft Teams, a Power Automate workflow that posts an adaptive card to a channel when it receives a webhook request.
  • In the Settings App, a workflow parameter that stores the webhook URL and a trigger on the Incidents class that runs a PowerShell command to send the card to that URL.

For e-mail notifications, see Author E-mail Notifications. How triggers and operations fit together in general is described in Workflow Overview.

Before you begin

  • To create the workflow parameter in the Settings App, you need the administrative right named Configuration Parameters; see Permissions Reference.
  • To add the trigger, you need the Incidents class's own administrative right, named after the class: Incidents. It gates the class's Workflow node.
  • Both the Configuration Parameters node and the Incidents class sit in the Workflow and Business Logic group, which is gated by the administrative right named Business Logic Management. The Configuration Parameters right and the class rights, such as Incidents, are child rights of Business Logic Management.

In Microsoft Teams

Create the Power Automate workflow

The workflow needs a Microsoft 365 account that is a member of the team the channel belongs to. The workflow uses that account to authenticate its connections and posts the cards on behalf of that account.

  1. In Microsoft Teams, go to the channel where the cards should appear. You can create a new channel for this purpose.
  2. In the upper-right corner next to the channel name, click the ellipsis button and select Workflows.
  3. In the list of workflow templates, select Post to a channel when a webhook request is received.
  4. Authenticate the workflow with the Microsoft 365 account.
  5. Click Add workflow. Power Automate creates the workflow and shows its webhook URL.
  6. Click Copy to copy the URL, and keep it. You store it in Alloy Navigator in the next part.
  7. Click Done.

NOTE: Any member of the team can add, change, or delete workflows when the Allow members to create, update, and remove connectors check box is selected in the team's Settings > Member permissions.

Design the adaptive card

The request that Alloy Navigator sends to the workflow carries an adaptive card: a JSON description built of elements such as text blocks, images, and fact sets. You can design the card in the Adaptive Cards Designer and copy its JSON from the designer's Card Payload Editor panel.

Design the card with sample values in its texts, not with Alloy Navigator placeholders. Not every character a field value can contain is valid in JSON, so the PowerShell script puts the Incident's values into the card when it runs. The example script contains a card of four text blocks: the ticket number as a link to the Incident, the summary, the requester, and the project.

In the Settings App

Store the webhook URL in a workflow parameter

In a new 2026.1 database created with the Default Workflow, the category tree of Configuration Parameters has a root category named Integrations, and no Microsoft Teams category; see Default Workflow Configuration. An upgraded database need not have this category, and an administrator may have changed the category tree.

  1. Go to Workflow and Business Logic > Advanced > Configuration Parameters.
  2. If you want a category of your own for the parameter, such as Microsoft Teams under Integrations, select the parent category in the category tree, for example Integrations, and click New Subcategory.
  3. On the toolbar of the parameter grid, click New. The Workflow Parameter window opens.
  4. Enter a Name, for example New Incidents Webhook, select a Type, and select the Category, for example Integrations > Microsoft Teams. These three fields are mandatory. The Category button opens the Select Category tree. For the webhook URL, the String and Encrypted types both work: with either type, the placeholder in your command yields the URL itself, escaped the same way. With String, the Settings App shows the URL as plain text; with Encrypted, it shows the value masked with asterisks, so you cannot check the URL by eye.
  5. Under Initial value, paste the webhook URL.
  6. Optionally, enter a Label (up to 100 characters) and a Description.
  7. Click OK. The page has no save button of its own: click Save on the main window's Standard toolbar, or select File > Save (Ctrl+S). Save is available only while there are unsaved changes.

Your command refers to the parameter by its name, not by its category: %[WFP New Incidents Webhook]%. After you save the parameter, its Usage tab searches for this placeholder.

To change the stored URL later, you do not need to open the parameter or the trigger: parameter values are also set under Workflow and Business Logic > Workflow Configuration, a node gated by the administrative right named Workflow Configuration. There, select the parameter's category, change the value, and click Save on the main window's Standard toolbar, or select File > Save (Ctrl+S). See Workflow Configuration and Parameters.

Add the trigger that posts the card

  1. Under Workflow and Business Logic > Service Desk > Incidents, select the class's Workflow node. The class's workflow tree opens.
  2. In that tree, select Triggers > On Created/Modified and click New. The Trigger on Create/Modify window opens.
  3. Enter a Name, which is mandatory, and a Description. Enabled is selected on a new trigger; leave it selected.
  4. Under Execute when:, leave Object is created selected. A new trigger starts with this option.
  5. Run this trigger only from the object Full Form is cleared on a new trigger. If you select it, the trigger runs for an Incident created from its full form and is skipped for an Incident created any other way, with two differences. An Incident created through the REST API or the Self Service Portal by a Create Action that has no form of its own still runs the trigger, as long as no attachments are submitted with it. An Incident created from its full form together with attached files or a detailed activity entry does not run the trigger.
  6. A condition on the Condition tab is optional.
  7. On the Programming tab, add an External Command. The External Command window opens with Run command on set to Client.
  8. Under Run command on, select Server. The Display PowerShell window option, shown only for Client, disappears, and the Timeout (min): box appears, with a value that starts at 1.
  9. In Command:, enter the PowerShell script that posts the card to the webhook URL, for example the example script. The button next to the box opens a larger Command editor, and Insert Placeholder... adds placeholders. See Placeholders in the command.
  10. Click OK. The window does not accept an empty command and checks the command's placeholders before it stores it.
  11. In the Trigger on Create/Modify window, click OK. This saves the trigger and closes the window.

NOTE: Server lets the card be posted whatever saved the Incident. A command that runs on the client runs only when an interactive application, such as the Web App, the Self Service Portal, or the API, started the workflow. The Mobile App works through the API, so a workflow it starts counts as started by the API. When a service started it, the command is refused, a message that external commands can run only on the server is recorded in the service log, and the workflow continues. A command that runs on the server is accepted whatever started the workflow and is queued for the Automation Server, so the request to Teams is sent from the Automation Server's computer.

The command is not run while the Incident is being saved. It is dispatched only after the Incident's changes are committed, so a save that fails posts no card.

A saved trigger or a changed parameter value reaches each application when that application next checks for workflow changes: the Web App checks at most every 30 seconds, and the Self Service Portal, the API, and the Automation Server at most every minute. Until then, an application can still run the workflow as it was before the change.

Example script

The script reads the webhook URL from the workflow parameter and the Incident's values from placeholders, puts the values into the card, and posts the card to the webhook. The card is the four-block card described under Design the adaptive card; to post your own design, replace the JSON between the single quotes of $card and the lines that set the texts of its elements.

# The webhook URL is stored as a workflow parameter in Alloy Navigator
$webHook = "%[WFP New Incidents Webhook]%"

# The Incident's values come from Alloy Navigator placeholders
$ticket = "%[DBF Ticket]%"
$title = "%[DBF Summary]%"
$creator = "%[DBF Requester_ID.Full_Name]%"
$project = "%[DBF Project_ID.Placement]%"
$viewUrl = "%[SYS Web Portal Link]%go/%[DBF Ticket]%"

# A prototype adaptive card with sample values
$card = '{
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "type": "AdaptiveCard",
    "version": "1.2",
    "body": [
        {
            "type": "Container",
            "items": [
                {
                    "type": "TextBlock",
                    "text": "[T000031](https://example.com/wp/go/T000031)",
                    "size": "Medium",
                    "wrap": true,
                    "weight": "Default"
                },
                {
                    "type": "TextBlock",
                    "text": "Unable to create a new site",
                    "isSubtle": true,
                    "spacing": "None",
                    "wrap": true,
                    "weight": "Bolder",
                    "size": "Medium"
                },
                {
                    "type": "TextBlock",
                    "text": "by Maxwell Newcomb",
                    "isSubtle": true,
                    "wrap": true,
                    "size": "Medium"
                },
                {
                    "type": "TextBlock",
                    "text": "in project M365 Rollout",
                    "isSubtle": true,
                    "spacing": "None",
                    "wrap": true,
                    "size": "Medium"
                }
            ]
        }
    ]
}'

$cardObject = $card | ConvertFrom-Json

$cardObject.body[0].items[0].text = "[$ticket]($viewUrl)"
$cardObject.body[0].items[1].text = $title
$cardObject.body[0].items[2].text = "by $creator"
$cardObject.body[0].items[3].text = "in project $project"

$bodyObject = [PSCustomObject] @{
    'type' = 'message';
    'attachments' = @(
        @{
            'contentType' = 'application/vnd.microsoft.card.adaptive';
            'contentUrl' = $null;
            'content' = $cardObject;
        }
    )
}

$body = $bodyObject | ConvertTo-Json -Depth 100

$Result = @([PSCustomObject] @{ Code = 0; Exception = ''; })

# Post the card to the webhook
Try {
    Invoke-RestMethod -uri $webHook -Method Post -body $body -ContentType 'application/json'
} Catch {
    $Result = @([PSCustomObject] @{ Code = 1; Exception = $_; })
}

If the request to the webhook fails, the script catches the exception and stores it in $Result. No card is posted, and the script does not retry.

After the trigger is saved, a card is posted to the channel each time the trigger runs for a new Incident. Clicking the ticket number in the card opens the Incident in the Web App when the lookup described under Placeholders in the command finds one match.

Placeholders in the command

When Alloy Navigator runs the command, it replaces each placeholder with its value. The value of a text, memo, GUID, date, time, date/time, lookup, multi-value, attachment, encrypted, or HTML field is written as plain text, escaped for use inside a double-quoted PowerShell string. An empty value of a field that is not a text field is written as $null. Alloy Navigator does not add the quotation marks itself. Put each such placeholder inside double quotes in your script; an unquoted value that contains a space, a $, or a quotation mark changes the command. How other field values are written is described under External Command in Operations Reference.

Placeholder Value
%[WFP New Incidents Webhook]% The webhook URL from your workflow parameter.
%[DBF Ticket]% The Incident's ticket number.
%[DBF Summary]% The Incident's summary.
%[SYS Web Portal Link]% The base address of the Web App, kept in the Web Portal Link system macro.

A script can also reach a field of an object that a lookup field refers to. The placeholder is then the chain of field names joined by dots: the Incident's Requester_ID lookup reaches the requester's Full_Name as %[DBF Requester_ID.Full_Name]%, and its Project_ID lookup reaches the project's Placement as %[DBF Project_ID.Placement]%. For macro placeholders, see Macros Reference.

To open the Incident from the card, link the card to %[SYS Web Portal Link]%go/%[DBF Ticket]%. Because a ticket number is not an object id, the Web App looks it up by name: one match opens the Incident, two to ten matches open the search results, and no match or more than ten matches opens an error page.

IMPORTANT: If you put the webhook placeholder in single quotes, as in '%[WFP New Incidents Webhook]%', the URL is inserted with the escaping meant for double quotes. This works only while the URL contains none of these characters: `, ", $, “, ”, „.