https://github.com/theapplefreak/winston-slack-webhook-transport
A Slack transport for Winston 3 that logs to a channel via webhooks
https://github.com/theapplefreak/winston-slack-webhook-transport
slack-logger slack-transport slack-webhook winston winston-transport winston3
Last synced: 13 days ago
JSON representation
A Slack transport for Winston 3 that logs to a channel via webhooks
- Host: GitHub
- URL: https://github.com/theapplefreak/winston-slack-webhook-transport
- Owner: TheAppleFreak
- License: mit
- Created: 2017-10-20T19:48:11.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2024-11-12T15:27:03.000Z (12 months ago)
- Last Synced: 2025-08-23T17:32:59.432Z (2 months ago)
- Topics: slack-logger, slack-transport, slack-webhook, winston, winston-transport, winston3
- Language: JavaScript
- Size: 1.68 MB
- Stars: 35
- Watchers: 1
- Forks: 13
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# winston-slack-webhook-transport
A Slack transport for Winston 3+ that logs to a channel via webhooks.
 [](https://www.npmjs.com/package/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.");
```