webhook

package
v1.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Feb 2, 2026 License: MIT Imports: 20 Imported by: 0

Documentation

Overview

Package webhook provides a webhook management system for NTM events. It supports async dispatch, retry with exponential backoff, event queueing, and optional HMAC signing for secure delivery.

Index

Constants

View Source
const (
	DefaultQueueSize       = 1000
	DefaultWorkerCount     = 10
	DefaultMaxRetries      = 5
	DefaultTimeout         = 10 * time.Second
	DefaultBaseBackoff     = 1 * time.Second
	DefaultMaxBackoff      = 30 * time.Second
	DefaultDeadLetterLimit = 100
)

Default configuration values

Variables

This section is empty.

Functions

This section is empty.

Types

type AttemptLog

type AttemptLog struct {
	Attempt    int
	Timestamp  time.Time
	StatusCode int
	Error      string
	Duration   time.Duration
}

AttemptLog records a single delivery attempt

type BuiltInFormat added in v1.7.0

type BuiltInFormat string
const (
	BuiltInFormatJSON    BuiltInFormat = "json"
	BuiltInFormatSlack   BuiltInFormat = "slack"
	BuiltInFormatDiscord BuiltInFormat = "discord"
	BuiltInFormatTeams   BuiltInFormat = "teams"
)

type BusBridge added in v1.7.0

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

BusBridge subscribes to an events.EventBus and dispatches webhook-compatible events to a WebhookManager.

func StartBridgeFromProjectConfig added in v1.7.0

func StartBridgeFromProjectConfig(projectDir, session string, bus *events.EventBus, redactionCfg *redaction.Config) (*BusBridge, error)

StartBridgeFromProjectConfig loads .ntm.yaml/.ntm.yml webhooks from projectDir, starts a WebhookManager, and subscribes it to the provided event bus.

If no webhooks are configured for the project, it returns (nil, nil).

func (*BusBridge) Close added in v1.7.0

func (b *BusBridge) Close() error

Close unsubscribes from the event bus and stops the underlying webhook manager.

type DeadLetter

type DeadLetter struct {
	Delivery   Delivery
	FailedAt   time.Time
	LastError  string
	AttemptLog []AttemptLog
}

DeadLetter represents a failed delivery that exhausted retries

type Delivery

type Delivery struct {
	ID        string
	Event     Event
	Webhook   *WebhookConfig
	Attempt   int
	NextRetry time.Time
	Error     error
}

Delivery represents a pending webhook delivery

type Event

type Event struct {
	ID        string            `json:"id"`
	Type      string            `json:"type"`
	Timestamp time.Time         `json:"timestamp"`
	Session   string            `json:"session,omitempty"`
	Pane      string            `json:"pane,omitempty"`
	Agent     string            `json:"agent,omitempty"`
	Message   string            `json:"message"`
	Details   map[string]string `json:"details,omitempty"`
}

Event represents a webhook event to be dispatched

type ManagerConfig

type ManagerConfig struct {
	QueueSize       int           `toml:"queue_size" json:"queue_size"`
	WorkerCount     int           `toml:"worker_count" json:"worker_count"`
	DefaultTimeout  time.Duration `toml:"default_timeout" json:"default_timeout,omitempty"`
	DeadLetterLimit int           `toml:"dead_letter_limit" json:"dead_letter_limit"`
}

ManagerConfig holds configuration for the WebhookManager

func DefaultManagerConfig

func DefaultManagerConfig() ManagerConfig

DefaultManagerConfig returns the default manager configuration

type RetryConfig

type RetryConfig struct {
	Enabled    bool          `toml:"enabled" json:"enabled"`
	MaxRetries int           `toml:"max_retries" json:"max_retries"`
	BaseDelay  time.Duration `toml:"base_delay" json:"base_delay,omitempty"`
	MaxDelay   time.Duration `toml:"max_delay" json:"max_delay,omitempty"`
}

RetryConfig holds retry policy for a webhook

func DefaultRetryConfig

func DefaultRetryConfig() RetryConfig

DefaultRetryConfig returns the default retry configuration

type Stats

type Stats struct {
	QueueLength     int   `json:"queue_length"`
	QueueCapacity   int   `json:"queue_capacity"`
	RetryQueueLen   int   `json:"retry_queue_length"`
	DeadLetterCount int   `json:"dead_letter_count"`
	Deliveries      int64 `json:"total_deliveries"`
	Failures        int64 `json:"total_failures"`
	DroppedEvents   int64 `json:"dropped_events"`
	WebhookCount    int   `json:"webhook_count"`
}

Stats returns current manager statistics

type WebhookConfig

type WebhookConfig struct {
	ID       string `toml:"id" json:"id"`
	Name     string `toml:"name" json:"name"`
	URL      string `toml:"url" json:"url"`
	Method   string `toml:"method" json:"method"`     // HTTP method (default POST)
	Template string `toml:"template" json:"template"` // Go template for payload
	// Format selects a built-in JSON payload formatter when Template is empty.
	// Supported: json, slack, discord, teams.
	Format  string            `toml:"format" json:"format"`
	Headers map[string]string `toml:"headers" json:"headers"`
	Events  []string          `toml:"events" json:"events"` // Event types to receive (empty = all)
	Enabled bool              `toml:"enabled" json:"enabled"`

	// Per-webhook timeout (overrides default)
	Timeout time.Duration `toml:"timeout" json:"timeout,omitempty"`

	// Retry configuration
	Retry RetryConfig `toml:"retry" json:"retry"`

	// HMAC signing configuration
	Secret string `toml:"secret" json:"secret,omitempty"` // HMAC-SHA256 secret
}

WebhookConfig holds configuration for a single webhook endpoint

type WebhookManager

type WebhookManager struct {

	// Logging callback (optional)
	Logger func(format string, args ...interface{})
	// contains filtered or unexported fields
}

WebhookManager manages webhook registration and event dispatch

func NewManager

func NewManager(cfg ManagerConfig) *WebhookManager

NewManager creates a new WebhookManager with the given configuration

func NewManagerWithRedaction added in v1.7.0

func NewManagerWithRedaction(cfg ManagerConfig, redactionCfg redaction.Config) *WebhookManager

NewManagerWithRedaction creates a webhook manager that redacts event content (message + details) before serialization/dispatch.

func (*WebhookManager) ClearDeadLetters

func (m *WebhookManager) ClearDeadLetters() int

ClearDeadLetters removes all entries from the dead letter queue

func (*WebhookManager) DeadLetters

func (m *WebhookManager) DeadLetters() []DeadLetter

DeadLetters returns a copy of the dead letter queue

func (*WebhookManager) Dispatch

func (m *WebhookManager) Dispatch(event Event) error

Dispatch queues an event for delivery to all matching webhooks

func (*WebhookManager) Register

func (m *WebhookManager) Register(cfg WebhookConfig) error

Register adds a webhook configuration to the manager

func (*WebhookManager) Start

func (m *WebhookManager) Start() error

Start begins background processing of the webhook queue

func (*WebhookManager) Stats

func (m *WebhookManager) Stats() Stats

Stats returns current manager statistics

func (*WebhookManager) Stop

func (m *WebhookManager) Stop() error

Stop gracefully shuts down the manager

func (*WebhookManager) Unregister

func (m *WebhookManager) Unregister(id string) error

Unregister removes a webhook by ID

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL