# winston-slack-webhook-transport

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

Latest version **2.3.7** (published 2026-10-27) · MIT license · 0 weekly downloads

## Install

```sh
npm install winston-slack-webhook-transport
pnpm add winston-slack-webhook-transport
yarn add winston-slack-webhook-transport
bun add winston-slack-webhook-transport
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 2.3.7 |
| Published | 2026-10-27 |
| First published | 2017-10-20 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 23.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 35 |
| Author | TheAppleFreak |
| Maintainers | theapplefreak |
| Keywords | winston, transport, slack, log, logger, logging, webhook |

## Links

- npm: https://www.npmjs.com/package/winston-slack-webhook-transport
- Repository: https://github.com/TheAppleFreak/winston-slack-webhook-transport
- Homepage: https://github.com/TheAppleFreak/winston-slack-webhook-transport#readme
- Issues: https://github.com/TheAppleFreak/winston-slack-webhook-transport/issues
- npm.io page: https://npm.io/package/winston-slack-webhook-transport

## Dependencies (2)

- [axios](https://npm.io/package/axios.md) ^1.20.0
- [winston-transport](https://npm.io/package/winston-transport.md) ^4.9.0

## Alternatives

- [cli-color](https://npm.io/package/cli-color.md) — 3.4M weekly downloads
- [log](https://npm.io/package/log.md) — 1.3M weekly downloads
- [logstash-client](https://npm.io/package/logstash-client.md) — 4.5K weekly downloads
- [@nocobase/plugin-logger](https://npm.io/package/@nocobase/plugin-logger.md) — 2.0K weekly downloads
- [child-process-debug](https://npm.io/package/child-process-debug.md) — 695 weekly downloads

## Recent versions

- 2.3.7 (latest) — 2026-10-27
- 2.3.6 — 2024-11-12
- 2.3.5 — 2024-03-21
- 2.3.4 — 2024-01-11
- 2.3.3 — 2023-11-11
- 2.3.2 — 2023-05-10
- 2.3.1 — 2023-05-10
- 2.3.0 — 2023-04-05
- 2.2.3 — 2023-03-03
- 2.2.2 — 2022-10-06
- 2.2.1 — 2022-10-06
- 2.2.0 — 2022-10-06
- 2.1.0 — 2021-10-04
- 2.0.1 — 2021-01-17
- 2.0.0 — 2020-08-14
- … 13 more at https://npm.io/package/winston-slack-webhook-transport/versions

## README

# winston-slack-webhook-transport

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

![Continuous Integration](https://github.com/TheAppleFreak/winston-slack-webhook-transport/actions/workflows/tests.yml/badge.svg) [![npm version](https://badge.fury.io/js/winston-slack-webhook-transport.svg)](https://www.npmjs.com/package/winston-slack-webhook-transport) [![downloads](https://img.shields.io/npm/dw/winston-slack-webhook-transport)](https://www.npmjs.com/package/winston-slack-webhook-transport)

## Installation

```
npm install winston winston-slack-webhook-transport
```

## Usage

### Set up with transports

```javascript
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

```javascript
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](https://api.slack.com/messaging/webhooks).
* `formatter` - Custom function to format messages with. This function accepts the `info` object ([see Winston documentation](https://github.com/winstonjs/winston/blob/master/README.md#streams-objectmode-and-info-objects)) and must return an object with at least one of the following three keys: `text` (string), `attachments` (array of [attachment objects](https://api.slack.com/reference/surfaces/formatting#attachments)), `blocks` (array of [layout block objects](https://api.slack.com/reference/surfaces/formatting#rich-layouts)). 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.](https://api.slack.com/reference/messaging/link-unfurling) (Default: `false`)
* `unfurlMedia` - Enables or disables [media unfurling.](https://api.slack.com/reference/messaging/link-unfurling) (Default: `false`)
* `mrkdwn` - Enables or disables [`mrkdwn` formatting](https://api.slack.com/reference/surfaces/formatting) within attachments or layout blocks (Default: `false`)
* `proxy` - Allows specifying a proxy server that [gets passed directly down to Axios](https://github.com/axios/axios#request-config) (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](https://www.webpagefx.com/tools/emoji-cheat-sheet/) 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](https://github.com/winstonjs/winston#awaiting-logs-to-be-written-in-winston). 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.](https://github.com/TheAppleFreak/winston-slack-webhook-transport/issues/24) 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](https://api.slack.com/reference/surfaces/formatting#rich-layouts) to create the desired layout. You can use the [Slack Block Kit Builder](https://api.slack.com/tools/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.

```javascript
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.");
```

---
_Source: https://npm.io/package/winston-slack-webhook-transport · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._