webhook

Documentation

Overview

Package webhook implements a generic webhook channel adapter that converts arbitrary JSON payloads into Envelopes using a configurable field mapping.

Index

• Constants
• Variables
• type Adapter
  • func New(name string, mapping FieldMapping) *Adapter
  • func NewWithOptions(name string, opts Options) *Adapter
  • func (a *Adapter) BoundAddr() string
  • func (a *Adapter) DroppedCount() uint64
  • func (a *Adapter) Inbound() <-chan *envelope.Envelope
  • func (a *Adapter) InboundHandler() http.Handler
  • func (a *Adapter) Manifest() channel.Manifest
  • func (a *Adapter) Name() string
  • func (a *Adapter) Receive(_ context.Context) (<-chan *envelope.Envelope, error)
  • func (a *Adapter) Send(ctx context.Context, env *envelope.Envelope) error
  • func (a *Adapter) SetOutboundURL(url string)
  • func (a *Adapter) Start(ctx context.Context) error
  • func (a *Adapter) Stop(ctx context.Context) error
• type FieldMapping
• type Options

Constants

const ChannelName = "webhook"

ChannelName is the registered type name of the webhook channel, mirroring telegram.ChannelName / discord.ChannelName. The app names the adapter with it.

Variables

var ErrAlreadyStarted = errors.New("webhook: already started")

ErrAlreadyStarted is returned by Start when the adapter's server is already running; the running server is left untouched.

Types

type Adapter

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

Adapter is a generic webhook channel that converts JSON payloads to/from Envelopes. It implements the channel.Channel interface, and — once built via NewWithOptions — the richer app.Channel (Start/Stop, see lifecycle.go).

func New

func New(name string, mapping FieldMapping) *Adapter

New creates a webhook adapter with the given name and field mapping.

func NewWithOptions

func NewWithOptions(name string, opts Options) *Adapter

NewWithOptions builds a wired webhook Adapter: the Stage-2 core (same inbound buffer and HTTP client, via New) plus the SP2 lifecycle options (ADR-0038 §2). The outbound URL keeps a SINGLE source of truth — opts.OutboundURL is copied into the existing outboundURL field through SetOutboundURL, which stays valid for tests and late binding (FR-COMPAT-1).

func (*Adapter) BoundAddr

func (a *Adapter) BoundAddr() string

BoundAddr returns the real address the server bound to (host:port, the actual port even under an ephemeral :0 bind), or "" until a successful Start (ADR-0038 §2).

func (*Adapter) DroppedCount

func (a *Adapter) DroppedCount() uint64

DroppedCount returns the cumulative number of inbound Envelopes dropped on a full buffer (ADR-0038 §5), the house drop seam registered as a pull metric.

func (*Adapter) Inbound

func (a *Adapter) Inbound() <-chan *envelope.Envelope

Inbound returns the read-only channel for received envelopes.

func (*Adapter) InboundHandler

func (a *Adapter) InboundHandler() http.Handler

InboundHandler returns an http.Handler that accepts incoming webhook POST requests, parses the JSON payload, and converts it to an Envelope.

func (*Adapter) Manifest

func (a *Adapter) Manifest() channel.Manifest

Manifest returns the capabilities of this webhook channel.

func (*Adapter) Name

func (a *Adapter) Name() string

Name returns the adapter's channel name.

func (*Adapter) Receive

func (a *Adapter) Receive(_ context.Context) (<-chan *envelope.Envelope, error)

Receive returns the inbound envelope channel, satisfying the Channel interface.

func (*Adapter) Send

func (a *Adapter) Send(ctx context.Context, env *envelope.Envelope) error

Send delivers an outbound Envelope as a JSON POST to the configured URL.

func (*Adapter) SetOutboundURL

func (a *Adapter) SetOutboundURL(url string)

SetOutboundURL configures the URL for outgoing webhook POST requests.

func (*Adapter) Start

func (a *Adapter) Start(ctx context.Context) error

Start brings the adapter's own HTTP server up (ADR-0038 §2), all-or-nothing: it binds a listener on the effective address (a bind failure returns a named, wrapped error and leaves the adapter un-started), records the real bound address (which matters under the ephemeral-port policy), mounts the EXISTING InboundHandler at the effective path plus a running-gated /healthz, and serves in a background goroutine. A serve error other than http.ErrServerClosed is logged (ADR-0008 §4a) since Start has already returned by then. Start is idempotent on an already-started adapter (returns ErrAlreadyStarted without disturbing the running server).

func (*Adapter) Stop

func (a *Adapter) Stop(ctx context.Context) error

Stop tears the server down, bounded by ctx, and is idempotent (ADR-0038 §2). An adapter that never started (including after a failed Start) returns nil immediately. A started adapter is shut down gracefully; if Shutdown errors (an unclean drain, or ctx already cancelled/expired), a Close() backstop guarantees the server is ALWAYS closed, the degradation is logged, and Stop still returns nil. The inbound channel is closed EXACTLY once (sync.Once) so the router pump sees a single clean end-of-stream (ADR-0008 ordering: channel stopped before router).

type FieldMapping

type FieldMapping struct {
	SenderID       string `json:"sender_id"`
	SenderName     string `json:"sender_name"`
	Text           string `json:"text"`
	MediaURL       string `json:"media_url"`
	MediaType      string `json:"media_type"`
	ConversationID string `json:"conversation_id"`
}

FieldMapping configures which JSON fields in the incoming payload map to Envelope fields.

type Options

type Options struct {
	Bind          string
	Path          string
	Secret        string
	OutboundURL   string
	OutboundToken string
	Mapping       FieldMapping
}

Options configures a wired webhook channel (ADR-0038 §2). Bind is the listen address (empty → defaultBind); Path is the inbound POST path (empty → defaultPath); Secret is the inbound shared secret VALUE, already resolved from its env var by the caller (env-only, ADR-0010 — never read here from a file); OutboundURL is where replies are POSTed (copied into the adapter's single outboundURL field, the one Send uses); OutboundToken is the OPTIONAL outbound downstream Bearer secret value; Mapping is the field mapping. The inbound-auth ENFORCEMENT of Secret lands in SP3; SP2 only carries it.