Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 18 additions & 17 deletions docs/english/web-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -633,33 +633,34 @@ Please note

---

## Proxy requests with a custom agent
## Proxy requests

The client allows you to customize the HTTP
[`Agent`](https://nodejs.org/docs/latest/api/http.html#http_class_http_agent) used to create the connection to Slack.
Using this option is the best way to make all requests from your app through a proxy, which is a common requirement in
many corporate settings.
The client sends requests with the [`fetch`](https://nodejs.org/docs/latest/api/globals.html#fetch) built into Node.js, which can route all requests from your app through a proxy. This is a common requirement in many corporate settings.

In order to create an `Agent` from some proxy information (such as a host, port, username, and password), you can use
one of many npm packages. We recommend [`https-proxy-agent`](https://www.npmjs.com/package/https-proxy-agent). Start
by installing this package and saving it to your `package.json`.
Set the [`NODE_USE_ENV_PROXY`](https://nodejs.org/docs/latest/api/cli.html#node_use_env_proxy1) environment variable to route requests through the proxy in your `HTTPS_PROXY`, `HTTP_PROXY`, and `NO_PROXY` environment variables. This requires Node.js v22.21.0, v24.0.0, or later.

```shell
$ npm install https-proxy-agent
$ NODE_USE_ENV_PROXY=1 HTTPS_PROXY=http://corporate.proxy:8080 node app.js
```

Import the `HttpsProxyAgent` class, and create an instance that can be used as the `agent` option of the `WebClient`.
On Node.js v24.14.0 and later, you can instead call [`http.setGlobalProxyFromEnv()`](https://nodejs.org/docs/latest/api/http.html#httpsetglobalproxyfromenvproxyenv) once at startup.

To use a proxy with a single `WebClient` or with an earlier version of Node.js, pass a `fetch` option with an [undici](https://undici.nodejs.org/) `ProxyAgent` as the `dispatcher`. Install the undici major version that matches your version of Node.js from the [long-term support table](https://undici.nodejs.org/#long-term-support), such as `undici@7` for Node.js v24.

```shell
$ npm install undici@7
```

```javascript
const { WebClient } = require('@slack/web-api');
const HttpsProxyAgent = require('https-proxy-agent');
const token = process.env.SLACK_TOKEN;
import { WebClient } from '@slack/web-api';
import { ProxyAgent } from 'undici';

// One of the ways you can configure HttpsProxyAgent is using a simple string.
// See: https://github.com/TooTallNate/node-https-proxy-agent for more options
const proxy = new HttpsProxyAgent(process.env.http_proxy || 'http://168.63.76.32:3128');
const token = process.env.SLACK_TOKEN;
const dispatcher = new ProxyAgent('http://corporate.proxy:8080');

const web = new WebClient(token, { agent: proxy });
const web = new WebClient(token, {
fetch: (input, init) => globalThis.fetch(input, { ...init, dispatcher }),
});

// All API method calls will now go through the proxy
```
Expand Down
45 changes: 21 additions & 24 deletions docs/english/webhook.md
Original file line number Diff line number Diff line change
Expand Up @@ -111,40 +111,37 @@ Only transient failures are retried: server errors (`5xx`) and network errors wi

---

## Proxy requests with a custom agent
## Proxy requests

The webhook allows you to customize the HTTP
[`Agent`](https://nodejs.org/docs/latest/api/http.html#http_class_http_agent) used to create the connection to Slack.
Using this option is the best way to make all requests from your app through a proxy, which is a common requirement in
many corporate settings.
The webhook sends requests with the [`fetch`](https://nodejs.org/docs/latest/api/globals.html#fetch) built into Node.js, which can route all requests from your app through a proxy. This is a common requirement in many corporate settings.

In order to create an `Agent` from some proxy information (such as a host, port, username, and password), you can use
one of many npm packages. We recommend [`https-proxy-agent`](https://www.npmjs.com/package/https-proxy-agent). Start
by installing this package and saving it to your `package.json`.
Set the [`NODE_USE_ENV_PROXY`](https://nodejs.org/docs/latest/api/cli.html#node_use_env_proxy1) environment variable to route requests through the proxy in your `HTTPS_PROXY`, `HTTP_PROXY`, and `NO_PROXY` environment variables. This requires Node.js v22.21.0, v24.0.0, or later.

```shell
$ npm install https-proxy-agent
$ NODE_USE_ENV_PROXY=1 HTTPS_PROXY=http://corporate.proxy:8080 node app.js
```

Import the `HttpsProxyAgent` class, and create an instance that can be used as the `agent` option of the
`IncomingWebhook`.
On Node.js v24.14.0 and later, you can instead call [`http.setGlobalProxyFromEnv()`](https://nodejs.org/docs/latest/api/http.html#httpsetglobalproxyfromenvproxyenv) once at startup.

To use a proxy with a single `IncomingWebhook` or with an earlier version of Node.js, pass a `fetch` option with an [undici](https://undici.nodejs.org/) `ProxyAgent` as the `dispatcher`. Install the undici major version that matches your version of Node.js from the [long-term support table](https://undici.nodejs.org/#long-term-support), such as `undici@7` for Node.js v24.

```shell
$ npm install undici@7
```

```javascript
const { IncomingWebhook } = require('@slack/webhook');
const HttpsProxyAgent = require('https-proxy-agent');
const url = process.env.SLACK_WEBHOOK_URL;
import { IncomingWebhook } from '@slack/webhook';
import { ProxyAgent } from 'undici';

// One of the ways you can configure HttpsProxyAgent is using a simple string.
// See: https://github.com/TooTallNate/node-https-proxy-agent for more options
const proxy = new HttpsProxyAgent(process.env.http_proxy || 'http://168.63.76.32:3128');
const url = process.env.SLACK_WEBHOOK_URL;
const dispatcher = new ProxyAgent('http://corporate.proxy:8080');

// Initialize with the proxy agent option
const webhook = new IncomingWebhook(token, { agent: proxy });
const webhook = new IncomingWebhook(url, {
fetch: (input, init) => globalThis.fetch(input, { ...init, dispatcher }),
});

// Sending this webhook will now go through the proxy
(async () => {
await webhook.send({
text: 'I\'ve got news for you...',
});
})();
await webhook.send({
text: 'I\'ve got news for you...',
});
```