webhook

package
v0.11.2 Latest Latest
Warning

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

Go to latest
Published: Oct 22, 2026 License: MIT Imports: 28 Imported by: 0

Documentation

Overview

Package webhook delivers newly received emails to configurable HTTP endpoints.

Index

Constants

This section is empty.

Variables

View Source
var ErrDeliveryReplayConflict = errors.New("webhook replay conflict")

ErrDeliveryReplayConflict identifies an ineligible or already pending replay.

Functions

This section is empty.

Types

type Attachment

type Attachment struct {
	FileName    string `json:"fileName"`
	ContentType string `json:"contentType"`
	Size        int64  `json:"size"`
}

Attachment is the safe attachment metadata exposed to webhook templates.

type Config

type Config struct {
	Version int      `json:"version,omitempty"`
	Targets []Target `json:"targets"`
}

Config is the top-level webhook forwarding configuration.

func LoadConfig

func LoadConfig(filePath string) (Config, error)

LoadConfig reads a strict JSON webhook configuration. Unknown fields and trailing JSON values are rejected so configuration mistakes fail at startup.

type DeliveryOutcome added in v0.11.0

type DeliveryOutcome struct {
	Target        string `json:"target"`
	StatusCode    int    `json:"status_code"`
	Attempts      int    `json:"attempts"`
	ErrorCategory string `json:"error_category,omitempty"`
}

DeliveryOutcome exposes diagnostic metadata without destination URLs or credentials.

type DeliveryRecord added in v0.11.0

type DeliveryRecord struct {
	ID          string            `json:"id"`
	EmailID     string            `json:"email_id"`
	RetryOf     string            `json:"retry_of,omitempty"`
	CompletedAt time.Time         `json:"completed_at"`
	Status      string            `json:"status"`
	Outcomes    []DeliveryOutcome `json:"outcomes"`
}

DeliveryRecord is a bounded terminal delivery summary. Payloads are not retained.

type Dispatcher

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

Dispatcher sends matching email events to configured targets.

func Load

func Load(filePath string, client *http.Client) (*Dispatcher, error)

Load creates a dispatcher from a JSON configuration file.

func NewDispatcher

func NewDispatcher(config Config, client *http.Client) (*Dispatcher, error)

NewDispatcher validates configuration and creates a dispatcher. Redirects are intentionally not followed so a configured target cannot redirect a payload or credentials to another host.

func (*Dispatcher) Dispatch

func (dispatcher *Dispatcher) Dispatch(ctx context.Context, email *types.Email) []Result

Dispatch waits for all matching HTTP targets. Normal server delivery uses DispatchDelivery from queue workers; SMTP acceptance waits for the durable local outbox handoff, not this network delivery. Direct callers block here.

func (*Dispatcher) DispatchDelivery

func (dispatcher *Dispatcher) DispatchDelivery(ctx context.Context, email *types.Email, deliveryID string) []Result

DispatchDelivery sends an email using a stable delivery ID. Durable queue consumers use this ID as the receiver's idempotency key.

func (*Dispatcher) TargetCount

func (dispatcher *Dispatcher) TargetCount() int

TargetCount returns the number of configured destinations.

type EmailPayload

type EmailPayload struct {
	ID              string                 `json:"id"`
	Time            time.Time              `json:"time"`
	Subject         string                 `json:"subject"`
	From            []string               `json:"from"`
	To              []string               `json:"to"`
	CC              []string               `json:"cc,omitempty"`
	BCC             []string               `json:"bcc,omitempty"`
	EnvelopeFrom    string                 `json:"envelopeFrom,omitempty"`
	EnvelopeTo      []string               `json:"envelopeTo,omitempty"`
	Text            string                 `json:"text"`
	HTML            string                 `json:"html,omitempty"`
	Size            int64                  `json:"size"`
	SizeHuman       string                 `json:"sizeHuman"`
	Attachments     []Attachment           `json:"attachments,omitempty"`
	Headers         map[string]interface{} `json:"-"`
	AttachmentCount int                    `json:"attachmentCount"`
}

EmailPayload is the stable email representation used by default payloads and custom body templates. It intentionally omits local file-system paths.

type Match

type Match struct {
	From    []string `json:"from,omitempty"`
	To      []string `json:"to,omitempty"`
	Subject []string `json:"subject,omitempty"`
	Text    []string `json:"text,omitempty"`
}

Match filters a target. Non-empty fields are ANDed, while patterns inside a field are ORed. Patterns use shell-style '*' and '?' wildcards and are matched case-insensitively.

type Result

type Result struct {
	Target     string
	StatusCode int
	Attempts   int
	Err        error
}

Result describes one target delivery attempt.

type Service

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

Service owns webhook queue workers and their cancellation/drain lifecycle.

func NewService

func NewService(dispatcher *Dispatcher, options ServiceOptions) (*Service, error)

NewService creates and starts a queued delivery service. Redis-backed mode uses a consumer-group stream and dead-letter stream; an empty Redis URL keeps a process-local queue while retaining cancellation and graceful drain.

func (*Service) Abort

func (service *Service) Abort(emailID string) error

Abort releases a staged handoff for a mail transaction that was rejected.

func (*Service) Close

func (service *Service) Close() error

Close stops accepting jobs, drains queued and active delivery until the configured deadline, then cancels remaining HTTP and Redis operations.

func (*Service) Commit

func (service *Service) Commit(emailID string) error

Commit makes staged outbox jobs consumable after the mail server has durably recorded acceptance. Calling it again is safe and supports startup recovery.

func (*Service) DeliveryHistory added in v0.11.0

func (service *Service) DeliveryHistory() ([]DeliveryRecord, bool)

DeliveryHistory returns detached terminal summaries and persistence health.

func (*Service) Enqueue

func (service *Service) Enqueue(email *types.Email) error

Enqueue durably hands an email to the local outbox when configured. Delivery remains at-least-once: receivers should deduplicate X-OwlMail-Delivery-ID.

func (*Service) RecoverAcceptedPending

func (service *Service) RecoverAcceptedPending() error

RecoverAcceptedPending promotes accepted jobs using durable fence state, independent of whether the email is still present in the mailbox.

func (*Service) RetryDelivery added in v0.11.0

func (service *Service) RetryDelivery(id string, email *types.Email) error

RetryDelivery replays only failed configured targets using the original idempotency key. The caller must supply a retained, detached email snapshot with the same ID.

type ServiceOptions

type ServiceOptions struct {
	RedisURL        string
	RedisPrefix     string
	MaxConcurrency  int
	ShutdownTimeout time.Duration
	SpoolDir        string
	OnResults       func(string, []Result)
}

ServiceOptions configures queued webhook delivery.

type Target

type Target struct {
	Name         string            `json:"name"`
	URL          string            `json:"url"`
	Method       string            `json:"method,omitempty"`
	Headers      map[string]string `json:"headers,omitempty"`
	ContentType  string            `json:"contentType,omitempty"`
	BodyTemplate string            `json:"bodyTemplate,omitempty"`
	Secret       string            `json:"secret,omitempty"`
	Timeout      string            `json:"timeout,omitempty"`
	Retries      int               `json:"retries,omitempty"`
	Match        Match             `json:"match,omitempty"`
}

Target describes one HTTP destination and the emails it should receive.

Jump to

Keyboard shortcuts

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