Test Microsoft Teams outgoing webhooks locally

Create the outgoing webhook firstCopy Anchor Link

Teams shows the security token once, in a dialog, after you create the webhook. Your handler needs that token, so create the webhook before you finish the handler. Start the tunnel in the next step, then follow Add the outgoing webhook in Teams.

Start your appCopy Anchor Link

Teams signs the request body. It sends an HMAC (a keyed hash) in the Authorization header as HMAC <base64 hash>. The algorithm is HMAC SHA256. The key is the security token, base64-decoded. The signed bytes are the raw body as UTF-8. Read the body with request.text() before you parse it.

Teams waits five seconds for a reply. The handler returns a JSON message that Teams posts in the thread.

import { createHmac, timingSafeEqual } from "node:crypto";

export async function POST(request: Request) {
  const securityToken = process.env.TEAMS_SECURITY_TOKEN;
  if (!securityToken) {
    return new Response("Missing TEAMS_SECURITY_TOKEN", { status: 500 });
  }

  const body = await request.text();
  const authorization = request.headers.get("authorization") ?? "";
  const received = authorization.replace(/^HMAC /, "");
  const expected = createHmac("sha256", Buffer.from(securityToken, "base64"))
    .update(body, "utf8")
    .digest("base64");

  const receivedBuffer = Buffer.from(received);
  const expectedBuffer = Buffer.from(expected);
  const isValid =
    receivedBuffer.length === expectedBuffer.length &&
    timingSafeEqual(receivedBuffer, expectedBuffer);

  if (!isValid) {
    return new Response("Invalid signature", { status: 401 });
  }

  const activity = JSON.parse(body);
  console.log(`Teams message from ${activity.from?.name}: ${activity.text}`);

  return Response.json({ type: "message", text: "Received by Horizon." });
}

Store the token in an environment variable once Teams shows it.

TEAMS_SECURITY_TOKEN=paste-the-token-teams-shows-you

Start the app on port 3000.

npm run dev

Start a tunnelCopy Anchor Link

Use -s with a subdomain you reserved. Without it, the subdomain is random and changes every run, so you would paste a new callback URL into Teams after each restart. Reserve it first on the Subdomains page. Reserved subdomains are a paid feature, see Pricing.

hrzn tunnel http://localhost:3000 -s my-teams-bot

Horizon prints HORIZON: Tunnel connected. Your public URL is https://my-teams-bot.hrzn.run. Keep this terminal open.

Add the outgoing webhook in TeamsCopy Anchor Link

1. Select Teams in the left pane.
2. Find your team and select the ••• menu, then Manage team.
3. Select the Apps tab.
4. Under Upload an app, select Create an outgoing webhook.
5. Set Name. Users type it after an @mention.
6. Set Callback URL to https://my-teams-bot.hrzn.run/api/webhooks/teams.
7. Set Description.
8. Select Create.

Teams shows the HMAC security token in a dialog. Copy it into TEAMS_SECURITY_TOKEN and restart npm run dev. The token doesn't expire, and each webhook has its own.

Trigger a requestCopy Anchor Link

Teams has no resend button for outgoing webhooks. Trigger a new request instead. In a public channel of the team, @mention the webhook by its Name and type a message. Teams only delivers messages that @mention the webhook, and only from public channels.