winston-slack-webhook-transport

winston-slack-webhook-transport

A Slack transport for Winston 3+ that logs to a channel via webhooks.

Installation

npm install winston winston-slack-webhook-transport

Usage

Set up with transports

const winston = require("winston");
const SlackHook = require("winston-slack-webhook-transport");

const logger = winston.createLogger({
    level: "info",
    transports: [
        new SlackHook({
            webhookUrl: "https://hooks.slack.com/services/xxx/xxx/xxx"
        })
    ]
});

logger.info("This should now appear on Slack");

Set up by adding

const winston = require("winston");
const SlackHook = require("winston-slack-webhook-transport");

const logger = winston.createLogger({});

logger.add(new SlackHook({ webhookUrl: "https://hooks.slack.com/services/xxx/xxx/xxx" }));

Options

• webhookUrl REQUIRED - Slack incoming webhook URL. Follow steps 1 through 3 at this link to create a new webhook if you don't already have one.
• formatter - Custom function to format messages with. This function accepts the info object (see Winston documentation) and must return an object with at least one of the following three keys: text (string), attachments (array of attachment objects), blocks (array of layout block objects). These will be used to structure the format of the logged Slack message. By default, messages will use the format of [level]: [message] with no attachments or layout blocks. A value of false can also be returned to prevent a message from being sent to Slack.
• level - Level to log. Global settings will apply if left undefined.
• unfurlLinks - Enables or disables link unfurling. (Default: false)
• unfurlMedia - Enables or disables media unfurling. (Default: false)
• mrkdwn - Enables or disables mrkdwn formatting within attachments or layout blocks (Default: false)
• proxy - Allows specifying a proxy server that gets passed directly down to Axios (Default: undefined)
• channel - Overrides the webhook's default channel. This should be a channel ID. (Default: undefined)
• username - Overrides the webhook's default username. (Default: undefined)
• iconEmoji - An emoji code string to use in place of the default icon. (Interchangeable with iconUrl) (Default: undefined)
• iconUrl - An icon image URL string to use in place of the default icon. Interchangeable with iconEmoji. (Default: undefined)
• emitAxiosErrors - Enables or disables emitting errors when Axios throws an error. This can occur if Slack returns a non-200 response code, such as 429 Too Many Requests. When disabled, Slack errors will be silently dropped, though if unhandled this can possibly lead to unexpected and transient crashes. Enable to handle those errors yourself. (Default: false)

Message formatting

winston-slack-webhook-transport supports the ability to format messages using Slack's message layout features. To do this, supply a custom formatter function that returns the requisite object structure to create the desired layout. You can use the Slack Block Kit Builder to quickly and easily prototype advanced layouts using Block Kit.

If for some reason you don't want to send a message to Slack, you can also return false to prevent the log message from being sent.

Formatters can also override the channel the message is posted to, username, and icon by defining the properties channel, username, iconEmoji, or iconUrl in the same object structure. These will override any options set in the transport constructor.

Note that if you're using Block Kit using either the attachments or blocks keys, the text parameter will function as a fallback for surfaces that do not support Block Kit, such as push notifications. It is recommended to include text when possible in these cases.

const winston = require("winston");
const SlackHook = require("winston-slack-webhook-transport");
 
const logger = winston.createLogger({
    level: "info",
    transports: [
        new SlackHook({
            webhookUrl: "https://hooks.slack.com/services/xxx/xxx/xxx",
            formatter: info => {
                return {
                    text: "This will function as a fallback for surfaces that don't support Block Kit, like IRC clients or mobile push notifications.",
                    blocks: [
                        {
                            type: "section",
                            text: {
                                type: "plain_text",
                                text: "You can pass more info to the formatter by supplying additional parameters in the logger call"
                            }
                        }
                    ],
                    attachments: [
                        {
                            text: "Or don't pass anything. That's fine too"
                        }
                    ]
                }
            }
        })
    ]
});

logger.info("Definitely try playing around with this.");

Changelog

2.3.6 (2024/11/12)

• No changes have been made to the code in this release.
• Updated dependencies so Dependabot would stop yelling at me.
• Fixed link rot in README.md and slightly updated one of the code examples so it reads better.