waigel / node-ms-teams-webhook Goto Github PK

Microsoft Teams webhook

License: Apache License 2.0

TypeScript 100.00%

node-ms-teams-webhook's Introduction

Microsoft Incoming Webhooks

This package helps you making requests to Microsoft Teams Incoming Webhooks. Use it in your application to send a notification to a channel.

Installation

$ npm install ms-teams-webhook

Usage

Initialize the webhook

The package exports a IncomingWebhook class. You'll need to initialize it with the URL you received from Microsoft Teams.

The URL can come from installation the Webhook Connector by right click on a channel > Incomming Webhook > Configuration > (insert a name) > Create

Javascript example:

const { IncomingWebhook } = require("ms-teams-webhook");

// Read a url from the environment variables
const url = process.env.MS_TEAMS_WEBHOOK_URL;

// Initialize
const webhook = new IncomingWebhook(url);

Typescript example:

import { IncomingWebhook } from "ms-teams-webhook";

// Read a url from the environment variables
const url = process.env.MS_TEAMS_WEBHOOK_URL;
if (!url) {
  throw new Error("MS_TEAMS_WEBHOOK_URL is required");
}

// Initialize
const webhook = new IncomingWebhook(url);

Send a webhook

You can use the "Editor for adaptive cards" in the Microsoft Teams Developer Portal

https://dev.teams.microsoft.com/cards

After you set up the webhook (see above), you can send a message to the channel by calling webhook.send().

(async () => {
  await webhook.send({
    "@type": "MessageCard",
    "@context": "https://schema.org/extensions",
    summary: "Issue 176715375",
    themeColor: "0078D7",
    title: 'Issue opened: "Push notifications not working"',
    sections: [
      {
        activityTitle: "Miguel Garcie",
        activitySubtitle: "9/13/2016, 11:46am",
        activityImage:
          "https://connectorsdemo.azurewebsites.net/images/MSC12_Oscar_002.jpg",
        text: "There is a problem with Push notifications, they don't seem to be picked up by the connector.",
      },
    ],
  });
})();

Credits go out to Slack. I took her Webhook lib as a template for this API.

node-ms-teams-webhook's People

Contributors

Stargazers

Watchers

Forkers

rocsys hypery2k

node-ms-teams-webhook's Issues

How can I attach photos? files?

can i attach photo to the sent message?

Question: How to mock this

How can I mock this in my tests?

Do you have a simple example, please?

Bad payload received by generic incoming webhook

Hi, about a week ago I discovered that my previously working teams notifications are not being received anymore, and upon investigation I found that version 2.0.1 seems to be affected by the following error:

      aborted: false,
      timeoutCb: null,
      upgradeOrConnect: false,
      parser: null,
      maxHeadersCount: null,
      reusedSocket: false,
      host: 'aib5.webhook.office.com',
      protocol: 'https:',
      [Symbol(kCapture)]: false,
      [Symbol(kBytesWritten)]: 0,
      [Symbol(kEndCalled)]: true,
      [Symbol(kNeedDrain)]: false,
      [Symbol(corked)]: 0,
      [Symbol(kOutHeaders)]: [Object: null prototype] {
        accept: [ 'Accept', 'application/json, text/plain, */*' ],
        'content-type': [ 'Content-Type', 'application/x-www-form-urlencoded' ],
        'user-agent': [ 'User-Agent', 'axios/0.21.4' ],
        'content-length': [ 'Content-Length', 608 ],
        host: [ 'Host', 'aib5.webhook.office.com' ]
      },
      [Symbol(kUniqueHeaders)]: null
    },
    data: 'Bad payload received by generic incoming webhook.'
  },
  isAxiosError: true,
  toJSON: [Function: toJSON]

when using the simple example as below:

async function sendTeamsNotification(payload) {
    const url = process.env.MS_TEAMS_WEBHOOK_URL
    const webhook = new IncomingWebhook(url)

    await webhook.send(JSON.stringify(payload))
}

The payload is a simple MS Teams Card which was validated via https://messagecardplayground.azurewebsites.net/
The same request works via cURL:
curl -H 'Content-Type: application/json' -d 'PAYLOAD' WEBHOOK

From the error above, notice the following:
'content-type': [ 'Content-Type', 'application/x-www-form-urlencoded' ],
I was able to replicate the error via curl by changing the content-type from json to urlencoded.

Judging by this, we need to be able to specify content-type or to figure out why it is sent as urlencoded

Question: how to improve troubleshooting

The JSON schema of the incoming webhook request payload is quite elaborate, and obscure at the same time. The Microsoft Teams API isn't making it too easy to troubleshoot deviations. An example is a response body of Bad payload received by generic incoming webhook. with an HTTP status code of 400... You get the point.

While there's little we can do to help Microsoft document its APIs better, the current implementation of the HTTP client request masks the few details the API returns in cases of failure. Specifically, the Error object thrown by axios in case of an HTTP 400 has .response.data as the response payload, but the .response object isn't serializable, and doesn't get logged properly.

I'd like to address this and make this library more helpful in troubleshooting scenarios. My question is what would be the preferred way to do so:

Replace the HTTP client being used to something that surfaces the response payload in case of an error. I personally like got, but open to other suggestions. I think got does a better job with error handling, need to validate this.
Handle the error thrown by axios as part of this library, and introduce some logic that glues Microsoft's API to user needs in a better way.
Some other option I didn't consider yet?