slack

Documentation

Overview

Package slack provides a lightweight client for sending messages to Slack via Incoming Webhooks.

Slack webhook reference: https://api.slack.com/messaging/webhooks

Problem

Posting to Slack webhooks directly from raw HTTP code introduces repeated boilerplate: JSON payload shaping, timeout handling, retries, optional sender metadata defaults (username/icon/channel), and status checks. Repeating that in each service increases integration drift and failure-handling inconsistencies.

This package centralizes those concerns behind a small client API.

What It Provides

• New creates a configured webhook client.
• Client.Send sends a text message with per-message overrides for username, icon emoji, icon URL, and channel, while falling back to client defaults.
• Client.HealthCheck performs an availability check against a status endpoint (default: Slack Status API) with a dedicated ping timeout.

Key Features

• Simple send API for webhook messages with sensible defaults.
• Optional per-message metadata overrides without reconstructing the client.
• Write-request retry strategy (via nurago httpretrier) for transient failures.
• Configurable HTTP behavior through options: WithTimeout, WithPingTimeout, WithPingURL, WithHTTPClient, WithRetryAttempts.
• Health checks suitable for readiness/liveness integrations.

Usage

c, err := slack.New(
    webhookURL,
    "my-bot",
    ":rocket:",
    "",
    "#deployments",
)
if err != nil {
    return err
}

if err := c.HealthCheck(ctx); err != nil {
    return err
}

err = c.Send(ctx,
    "deployment succeeded",
    "", // use default username
    "", // use default icon emoji
    "", // use default icon URL
    "", // use default channel
)
if err != nil {
    return err
}

This package is ideal for Go services that need a minimal, dependable Slack notification integration without hand-writing webhook request plumbing.

Index

• Variables
• type Client
  • func New(addr, username, iconEmoji, iconURL, channel string, opts ...Option) (*Client, error)
  • func (c *Client) HealthCheck(ctx context.Context) (err error)
  • func (c *Client) Send(ctx context.Context, text, username, iconEmoji, iconURL, channel string) error
• type HTTPClient
• type Option
  • func WithHTTPClient(hc HTTPClient) Option
  • func WithPingTimeout(timeout time.Duration) Option
  • func WithPingURL(pingURL string) Option
  • func WithRetryAttempts(attempts uint) Option
  • func WithRetryDelay(value time.Duration) Option
  • func WithTimeout(timeout time.Duration) Option

Variables

var (
	// ErrInvalidAddress is returned by New when the webhook address is missing,
	// unparseable, or lacks a scheme or host. The offending address is not
	// echoed in the wrapped error because the webhook URL is a secret.
	ErrInvalidAddress = errors.New("slack: invalid webhook address")

	// ErrInvalidRetryConfig is returned by New when the retry options are invalid.
	ErrInvalidRetryConfig = errors.New("slack: invalid retry configuration")
)

Exported sentinel errors returned by this package. Match them with errors.Is.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client sends Slack webhook messages and performs Slack status health checks.

func New

func New(addr, username, iconEmoji, iconURL, channel string, opts ...Option) (*Client, error)

New constructs a Slack webhook client with defaults for timeout, retries, and optional message metadata. Parameters other than addr are optional defaults that can be overridden per Send call.

func (*Client) HealthCheck

func (c *Client) HealthCheck(ctx context.Context) (err error)

HealthCheck verifies the Slack status endpoint is reachable and reports no active incident affecting webhook delivery.

It confirms the status endpoint returns HTTP 200 with a decodable body, then inspects active_incidents and returns an error only when an ongoing (not "resolved") incident affects the Apps/Integrations/APIs service, since that is the service webhook delivery depends on. Unrelated Slack incidents do not fail the check. The response shape follows the Slack status API v2.0.0 "current" endpoint.

func (*Client) Send

func (c *Client) Send(ctx context.Context, text, username, iconEmoji, iconURL, channel string) error

Send posts a message to Slack webhook, using client defaults for empty metadata arguments.

type HTTPClient

type HTTPClient interface {
	Do(req *http.Request) (*http.Response, error)
}

HTTPClient is the minimal HTTP transport contract used by Client.

type Option

type Option func(c *Client)

Option applies a configuration change to Client.

func WithHTTPClient

func WithHTTPClient(hc HTTPClient) Option

WithHTTPClient injects a custom HTTP client implementation.

func WithPingTimeout

func WithPingTimeout(timeout time.Duration) Option

WithPingTimeout sets timeout used by HealthCheck.

func WithPingURL

func WithPingURL(pingURL string) Option

WithPingURL overrides the Slack status endpoint used by HealthCheck.

func WithRetryAttempts

func WithRetryAttempts(attempts uint) Option

WithRetryAttempts sets max retry attempts for webhook sends.

func WithRetryDelay

func WithRetryDelay(value time.Duration) Option

WithRetryDelay sets the base delay between a failed webhook send and its retry (default: httpretrier.DefaultDelay, 1 s). Must be positive (New rejects non-positive values).

func WithTimeout

func WithTimeout(timeout time.Duration) Option

WithTimeout sets webhook request timeout.

It is applied only to the default HTTP client that New creates; it has no effect when a custom client is supplied via WithHTTPClient (that client owns its own timeout).