@emito/provider-slack

Slack Incoming Webhook delivery adapter for the Emito notification engine.

What it is

@emito/provider-slack is the Slack channel provider for Emito. It implements the ProviderPlugin contract from @emito/types and delivers messages by POSTing a JSON payload to a Slack Incoming Webhook URL. The payload carries both blocks (Slack Block Kit) and a text fallback, and HTTP failures are mapped onto Emito's typed EmitoError codes so the engine can decide whether to retry.

The provider holds no credentials of its own — the destination webhookUrl arrives per delivery in the channel params, so a single provider instance serves every tenant and every workspace.

Install

@emito/provider-slack is a workspace package in the Emito monorepo and is not yet published to npm. Inside the monorepo, depend on it with the workspace protocol:

// package.json
{
  "dependencies": {
    "@emito/provider-slack": "workspace:*"
  }
}

@emito/types is a workspace dependency and resolves through the workspace. Standalone publishing to npm is planned.

Usage

import { createSlackProvider } from "@emito/provider-slack";

const slack = createSlackProvider();

const result = await slack.deliver({
  channel: "slack",
  webhookUrl: "https://hooks.slack.com/services/T000/B000/XXXX",
  text: "Build #1429 passed",
  blocks: [
    {
      type: "section",
      text: { type: "mrkdwn", text: "*Build #1429* passed :white_check_mark:" },
    },
  ],
  metadata: {
    notificationId: "ntf_123",
    subscriberId: "sub_456",
    eventType: "build.passed",
  },
});

// result.success === true on a 2xx response from Slack

Within Emito you register the provider with the engine rather than calling deliver directly; the engine resolves the slack channel to this plugin.

Injecting a custom fetch

createSlackProvider accepts an optional fetchFn so you can supply your own fetch implementation — useful for tests, instrumentation, or a non-global client.

const slack = createSlackProvider({ fetchFn: myFetch });

Request deadline

Every request carries a 10 second deadline so a stalled webhook cannot hold a delivery worker open indefinitely. Override it with timeoutMs:

const slack = createSlackProvider({ timeoutMs: 3_000 });

API surface

| Export | Kind | Description | | --- | --- | --- | | createSlackProvider(options?) | function | Builds a ProviderPlugin with name/channel set to "slack". | | options.fetchFn | typeof fetch (optional) | Custom fetch implementation; defaults to globalThis.fetch. | | options.timeoutMs | number (optional) | Per-request deadline; defaults to 10_000. |

The returned ProviderPlugin exposes:

| Member | Signature | Behavior | | --- | --- | --- | | deliver | (params: ChannelDeliveryParams) => Promise<DeliveryResult> | POSTs { blocks, text } to webhookUrl; resolves { success: true } on a 2xx response, throws an EmitoError otherwise. | | healthCheck | () => Promise<boolean> | Always resolves true (webhook delivery is stateless). |

Error mapping

Non-2xx responses are translated into EmitoError instances with codes from @emito/types, carrying the retry hint the engine uses:

| HTTP status | EMITO_ERROR_CODE | Retryable | | --- | --- | --- | | 429 | RATE_LIMITED | yes | | 404 | DELIVERY_INVALID_ADDRESS | no | | 5xx | PROVIDER_UNAVAILABLE | yes | | other non-2xx | DELIVERY_REJECTED | no |

A request that exceeds the deadline becomes a retryable PROVIDER_TIMEOUT. Other network-level failures (a rejected fetch) become a retryable PROVIDER_UNAVAILABLE error carrying the original as cause.

Part of Emito

@emito/provider-slack is one package in the Emito monorepo — self-hosted, provider-agnostic notification infrastructure for Node.js and TypeScript.

• Shared contracts — @emito/types
• Core engine — @emito/core
• Telegram provider — @emito/provider-telegram
• See the full package list in the root README.

License

MIT — part of the Emito project.