Documentation
¶
Overview ¶
Package webhook delivers newly received emails to configurable HTTP endpoints.
Index ¶
- Variables
- type Attachment
- type Config
- type DeliveryOutcome
- type DeliveryRecord
- type Dispatcher
- type EmailPayload
- type Match
- type Result
- type Service
- func (service *Service) Abort(emailID string) error
- func (service *Service) Close() error
- func (service *Service) Commit(emailID string) error
- func (service *Service) DeliveryHistory() ([]DeliveryRecord, bool)
- func (service *Service) Enqueue(email *types.Email) error
- func (service *Service) RecoverAcceptedPending() error
- func (service *Service) RetryDelivery(id string, email *types.Email) error
- type ServiceOptions
- type Target
Constants ¶
This section is empty.
Variables ¶
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 ¶
Config is the top-level webhook forwarding configuration.
func LoadConfig ¶
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 ¶
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 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) Close ¶
Close stops accepting jobs, drains queued and active delivery until the configured deadline, then cancels remaining HTTP and Redis operations.
func (*Service) Commit ¶
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 ¶
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 ¶
RecoverAcceptedPending promotes accepted jobs using durable fence state, independent of whether the email is still present in the mailbox.
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.