webhook

type Algorithm ¶

type Algorithm string

Algorithm is the webhook signing algorithm marker. HMAC-SHA256 is the only legal value (see ADR webhook-signing-algorithm); SHA-1 and other downgrades are rejected by Algorithm.Validate.

const AlgorithmHMACSHA256 Algorithm = "hmac-sha256"

func (a Algorithm) String() string

func (a Algorithm) Validate() error

type Delivery ¶

type Delivery struct {
	// DeliveryID is the per-delivery identifier extracted from the configured
	// DeliveryIDHeader and validated before signature verification.
	DeliveryID DeliveryID

	// SourceID is the secret-isolation key that was used to verify this
	// delivery (i.e. the ReceiverSpec.SourceID that matched the inbound request).
	SourceID SourceID

	// Headers are the signature headers that were verified: DeliveryID,
	// Timestamp, and Signature. Re-using webhook.Headers avoids a parallel
	// type; the runtime has already checked all three fields before delivery.
	Headers Headers

	// Payload is the raw request body after signature verification. The slice
	// is owned by the receiver runtime; handlers must not retain it past the
	// handler call.
	Payload []byte
}

Delivery carries the fully-verified context of an inbound webhook request. The receiver runtime populates a Delivery after reading the body, validating the HMAC signature, and claiming the delivery ID for idempotency. Handlers receive a Delivery and must not mutate its Payload slice.

type DeliveryID ¶

type DeliveryID string

DeliveryID is the typed per-delivery identifier. It doubles as the idempotency key on the receiver side and is part of the signed content, so it must not contain whitespace. Construct via NewDeliveryID.

func NewDeliveryID(s string) (DeliveryID, error)

func (id DeliveryID) String() string

func (id DeliveryID) Validate() error

type DispatchSpec ¶

type DispatchSpec struct {
	ContractID string
	// SourceID is the signing-secret source: it selects the secret used to
	// sign outbound webhook requests sent to the external target. The peer
	// concept is ReceiverSpec.SourceID, which selects the secret for verifying
	// inbound webhook requests.
	SourceID string
	CellID   string
}

DispatchSpec is the pure-data descriptor cellgen emits to register an outbound webhook dispatcher. SourceID names the signing-secret source: it selects the signing secret used when signing outbound requests to the external target (the counterpart of ReceiverSpec.SourceID which selects the secret for verifying inbound requests). The reg.RegisterWebhookDispatch Registrar method and the dispatcher runtime land in PR-5.

func (s DispatchSpec) Validate() error

type Dispatcher ¶

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

Dispatcher delivers an outbound webhook for each consumed outbox outbox.Entry: it selects the target URL, vets it against the SSRF policy, HMAC-signs the payload, POSTs it, and maps the outcome to an outbox.HandleResult. It implements outbox.EntryHandler via Dispatcher.Handle.

Construct via NewDispatcher; the zero value is invalid. All HTTP egress flows through an *http.Client built from the injected SafePolicy — there is no client-injection option, so SSRF protection cannot be bypassed (WEBHOOK-SSRF-GUARD-01 downstream; see tools/archtest/webhook_ssrf_guard_test.go).

func NewDispatcher(
	clk clock.Clock,
	signer Signer,
	policy *SafePolicy,
	selector WebhookDispatchSelector,
	opts ...DispatcherOption,
) (*Dispatcher, error)

func (d *Dispatcher) Handle(ctx context.Context, entry outbox.Entry) outbox.HandleResult

2xx                                    → Ack
non-2xx (3xx/4xx/5xx) / timeout / conn  → Requeue (transient; standard-webhooks aligned)
SSRF-blocked transport / bad config     → Reject  (permanent → DLX)

type DispatcherOption ¶

type DispatcherOption func(*Dispatcher)

DispatcherOption customizes a Dispatcher at construction time.

func WithDeliveryTimeout(d time.Duration) DispatcherOption

func WithMetrics(rec Metrics, source string) DispatcherOption

type Headers ¶

type Headers struct {
	DeliveryID DeliveryID
	Timestamp  string
	Signature  string
}

Headers is the INBOUND signature-header DTO that a Verifier consumes. The receiver constructs it from the raw request headers (untrusted input), so its fields are exported by design — a forged Headers simply fails Verifier.Verify. The OUTBOUND, provenance-sealed counterpart written to the wire is SignedHeaders (produced only by Signer.Sign); the two are deliberately distinct types so the wire-write path cannot be fed a hand-built value (#1492).

Timestamp is unix seconds as a decimal string; Signature is one or more space-separated "v1,<base64>" tokens.

type Metrics ¶

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

Metrics holds the optional pre-bound webhook instruments. A nil field disables that instrument (every record method nil-checks before recording), so a zero Metrics value — the disabled / NopProvider case — is a safe no-op. Build via RegisterMetrics at the composition root (bootstrap auto-wire) and inject into both the Dispatcher (dispatch side) and the runtime Receiver (receive side); one instance serves both, the instrument sets are disjoint.

The instrument fields are intentionally UNEXPORTED. This seals the upstream of the WEBHOOK-METRIC-LABEL-VALUES-FROZEN-01 funnel: outside kernel/webhook the only metric-write surface is the record* methods below (recordDelivery / observeDeliveryDuration / RecordSignatureFailure / RecordIdempotencyHit), which take the sealed typed label enums — there is no `m.Deliveries.With(Labels{...})` escape hatch for a holder to write an off-set label value. Within the package a new struct cannot be populated except by RegisterMetrics (the sole constructor), and the WEBHOOK-METRIC-LABEL-VALUES-FROZEN-01 callsite guard locks the `.With(...)` calls to the record* method bodies. See tools/archtest/webhook_metric_label_values_frozen_test.go.

func RegisterMetrics(p kernelmetrics.Provider) (Metrics, error)

func (m Metrics) RecordIdempotencyHit(ctx context.Context, source string)

func (m Metrics) RecordSignatureFailure(ctx context.Context, source string, reason SignatureFailureReason)

type ReceiverSpec ¶

type ReceiverSpec struct {
	ContractID string
	// SourceID is the secret-isolation key: it selects the signing secret used
	// to verify the HMAC signature on inbound webhook requests from the external
	// source. Must match contract.yaml endpoints.inbound.sourceID.
	SourceID string
	CellID   string

	// Runtime configuration — cellgen bakes these from contract.yaml fields.
	// PathPattern is the URL path pattern the receiver runtime mounts
	// (contract.yaml endpoints.inbound.pathPattern).
	PathPattern string
	// DeliveryIDHeader is the HTTP header name carrying the per-delivery
	// identifier (contract.yaml signature.deliveryIDHeader).
	DeliveryIDHeader string
	// TimestampHeader is the HTTP header name carrying the unix-seconds
	// timestamp that is part of the signed content
	// (contract.yaml signature.timestampHeader).
	TimestampHeader string
	// SignatureHeader is the HTTP header name carrying the space-separated
	// "v1,<base64>" HMAC tokens (contract.yaml signature.signatureHeader).
	SignatureHeader string
	// ToleranceSeconds is the bidirectional timestamp window in seconds within
	// which a signed delivery is accepted (contract.yaml
	// signature.toleranceSeconds). Must be > 0.
	ToleranceSeconds int64
	// MaxBodyBytes is the maximum accepted request body size in bytes
	// (contract.yaml payload.maxBodyBytes). Must be > 0.
	MaxBodyBytes int64
}

ReceiverSpec is the pure-data descriptor cellgen emits into cell_gen.go to register an inbound webhook receiver. ContractID, SourceID, and CellID are the code-generation-time identifiers (stable since PR-2); PathPattern, DeliveryIDHeader, TimestampHeader, SignatureHeader, ToleranceSeconds, and MaxBodyBytes are the receiver runtime configuration that cellgen bakes from contract.yaml (signature / endpoints.inbound / payload sections) in batch B.

The reg.RegisterWebhookReceiver Registrar method and its bootstrap drain land in PR-3 (receiver runtime). This struct is the cellgen ↔ runtime seam; the dispatch counterpart is DispatchSpec.

func (s ReceiverSpec) Validate() error

type RetrySchedule ¶

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

RetrySchedule is the fixed sequence of wait intervals between outbound delivery retries. The first delivery attempt is immediate; delays[i] is the wait before retry i+1. The schedule is value-immutable: DefaultSvixSchedule returns a fresh copy and there is no setter.

DefaultSvixSchedule is the canonical default. The per-attempt wall-clock delays ARE honored at runtime (gh #1458): the webhook-dispatch bootstrap drain copies Delays() onto outbox.Subscription.BrokerDelaySchedule, and the Subscriber applies broker-native delayed re-delivery (rabbitmq TTL+DLX delay-tier queues / in-memory clock-timed schedule), durable across restarts. DelayFor is the single-tier lookup; Delays is the bulk seam the wiring consumes.

See docs/architecture/202606012052-1160-adr-webhook-retry-default.md §D5.

func DefaultSvixSchedule() RetrySchedule

func (s RetrySchedule) Attempts() int

func (s RetrySchedule) DelayFor(n int) (delay time.Duration, ok bool)

func (s RetrySchedule) Delays() []time.Duration

func (s RetrySchedule) MaxRetries() int

type SafeDialContext ¶

type SafeDialContext func(ctx context.Context, network, address string) (net.Conn, error)

SafeDialContext is the dial function signature shared with net.Dialer.DialContext, so SafePolicy.DialContext drops directly into http.Transport.DialContext (wired by the dispatcher in PR-5).

type SafeOption ¶

type SafeOption func(*SafePolicy)

SafeOption customizes a SafePolicy at construction time.

func WithAllowLoopback() SafeOption

type SafePolicy ¶

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

SafePolicy is the single source of webhook outbound SSRF policy. Its three methods — DialContext (resolve→vet→dial-literal), ValidateTargetURL (cheap pre-flight) and DenyRedirect (redirect deny-all) — all share one config, so a policy knob (e.g. WithAllowLoopback) applies identically to the pre-flight and the dial. PR-5 holds one *SafePolicy and wires all three into an *http.Client; there is no divergent per-surface vetting path.

DialContext resolves the host, vets every resolved IP against the SSRF blocklist, then dials a vetted IP literal — closing the DNS-rebinding (TOCTOU) window because the connection target is the already-checked literal, never a re-resolved hostname.

ref: stripe/smokescreen pkg/smokescreen (resolve→vet→dial-literal) ref: stealthrocket/netjail security.go Rules.DialFunc ref: doyensec/safeurl ip.go privateNetworks (CIDR superset; Control mode not used)

func NewSafePolicy(opts ...SafeOption) *SafePolicy

func (p *SafePolicy) DenyRedirect(_ *http.Request, via []*http.Request) error

func (p *SafePolicy) DialContext(ctx context.Context, network, address string) (net.Conn, error)

func (p *SafePolicy) ValidateTargetURL(rawURL string) error

type SignatureFailureReason ¶

type SignatureFailureReason string

SignatureFailureReason is the exported sealed string type for the webhook_signature_failures_total{reason=...} label. It is exported because the receive-side classification happens in runtime/webhook (the Receiver's verify step), which returns a typed reason that flows into Metrics.RecordSignatureFailure. The value set is enumerable by TYPE; the WEBHOOK-METRIC-LABEL-VALUES-FROZEN-01 archtest freezes it.

The wire 401 is deliberately uniform for ReasonUnknownSource and ReasonBadSignature (anti-enumeration oracle, see the Receiver verify godoc), but the server-side metric distinguishes them — the metric is not a wire oracle, and missing/invalid/unknown/bad/expired enable distinct alerts (the Kubernetes admission error_type / Vault audit reason precedent).

const (
	// ReasonMissingHeader: one or more required signature headers were absent.
	ReasonMissingHeader SignatureFailureReason = "missing_header"
	// ReasonInvalidHeader: a header was present but unparseable (bad delivery
	// id, non-integer timestamp).
	ReasonInvalidHeader SignatureFailureReason = "invalid_header"
	// ReasonUnknownSource: the configured source id was not registered in the
	// source store.
	ReasonUnknownSource SignatureFailureReason = "unknown_source"
	// ReasonBadSignature: the HMAC did not match for any candidate secret.
	ReasonBadSignature SignatureFailureReason = "bad_signature"
	// ReasonTimestampExpired: the timestamp skew exceeded the tolerance window.
	ReasonTimestampExpired SignatureFailureReason = "timestamp_expired"
)

type SignedHeaders ¶

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

SignedHeaders is the provenance-sealed OUTBOUND signature-header set: the value Signer.Sign produces and SignedHeaders.Apply writes onto an outbound request. All fields are unexported, INCLUDING a `valid` provenance flag that only Signer.Sign sets. A package-external caller can neither build a populated literal (unexported fields) nor set `valid` on a zero value, so it cannot obtain a valid SignedHeaders; SignedHeaders.Apply fail-closes (writes nothing) on a zero value. Hence the only SignedHeaders that can write to the wire is one produced by the sealed Signer.Sign = WEBHOOK-SIGNER-FUNNEL-01 upstream Hard (external; #1492, valid-token closure of the zero-value-construction gap found in review #1733 F1 — unexported fields alone do NOT stop `var h SignedHeaders`). The in-package `SignedHeaders{valid: true}` literal remains the permanent Go ceiling (same family as #851/#893/#1282/#1375). This is the outbound counterpart to the inbound Headers parse DTO.

func (h SignedHeaders) Apply(header http.Header)

func (h SignedHeaders) DeliveryID() DeliveryID

func (h SignedHeaders) Signature() string

func (h SignedHeaders) Timestamp() string

type Signer ¶

type Signer interface {
	// Sign computes the sealed signature headers for payload at time ts under
	// deliveryID. ts is supplied by the caller (the dispatcher passes its
	// clock's Now) so the signer holds no clock.
	Sign(payload []byte, ts time.Time, deliveryID DeliveryID) (SignedHeaders, error)
	// contains filtered or unexported methods
}

Signer produces a sealed SignedHeaders for an outbound webhook delivery. The interface is sealed (unexported sealed() marker): the sole implementation is the HMAC-SHA256 signer from NewHMACSigner, so package-external types cannot satisfy Signer (WEBHOOK-HMAC-FUNNEL-01/A3 upstream).

func NewHMACSigner(source Source) (Signer, error)

type Source ¶

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

Source is an opaque webhook source: an identifier plus the shared secret used to sign/verify its deliveries. The secret is an unexported field with no getter — in-package signer/verifier read it directly, package-external callers can only construct a Source via NewSource and never read the secret back. Source.LogValue redacts the secret so slog of a Source is always safe.

func NewSource(id SourceID, secret []byte) (Source, error)

func (s Source) GoString() string

func (s Source) ID() SourceID

func (s Source) LogValue() slog.Value

func (s Source) String() string

type SourceID ¶

type SourceID string

SourceID is the typed identifier for a webhook source — the secret-isolation key under which a Source is registered. Construct via NewSourceID; the validator mirrors kernel/healthz.ProbeName (snake/kebab lowercase identifier).

func NewSourceID(s string) (SourceID, error)

func (id SourceID) String() string

func (id SourceID) Validate() error

type SourceRegistry ¶

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

SourceRegistry is an in-memory SourceStore. It is safe for concurrent use and is the default for single-process deployments, tests, and demos.

func NewSourceRegistry() *SourceRegistry

func (r *SourceRegistry) Lookup(id SourceID) (Source, bool)

func (r *SourceRegistry) Register(src Source) error

type SourceStore ¶

type SourceStore interface {
	// Lookup returns the source registered under id and true, or the zero
	// Source and false when id is unknown.
	Lookup(id SourceID) (Source, bool)
}

SourceStore resolves a SourceID to its registered Source. The receiver looks up the secret for an inbound delivery through this interface, so a persistent / encrypted backing store (configcore, Vault) can replace the in-memory default without touching the verification path.

type Verifier ¶

type Verifier interface {
	// Verify returns nil when rawBody, headers, and source produce a matching
	// HMAC within the tolerance window; otherwise it returns a typed
	// *errcode.Error sentinel (ErrWebhookInvalidHeader / TimestampExpired /
	// InvalidSignature / ConfigInvalid).
	Verify(rawBody []byte, headers Headers, source Source) error
	// contains filtered or unexported methods
}

Verifier checks the signature Headers of an inbound webhook against a Source's secret. The interface is sealed (unexported sealed() marker): the sole implementation is the HMAC-SHA256 verifier from NewHMACVerifier (WEBHOOK-HMAC-FUNNEL-01/A3 upstream).

func NewHMACVerifier(clk clock.Clock, opts ...VerifierOption) (Verifier, error)

type VerifierOption ¶

type VerifierOption func(*hmacVerifier)

VerifierOption configures NewHMACVerifier; use WithTolerance to override defaults.

func WithTolerance(d time.Duration) VerifierOption

type WebhookDispatchSelector ¶

type WebhookDispatchSelector func(ctx context.Context, payload []byte) (string, error)

WebhookDispatchSelector is the outbound-webhook target-selector signature cellgen emits as the second argument to reg.RegisterWebhookDispatch. Given an outbound payload it returns the target identifier the dispatcher runtime uses to route and sign the request; a non-nil error signals the dispatcher to skip or fail the dispatch.

PR-2 record-only seam: like WebhookReceiveHandler this is intentionally minimal (stdlib types only). The PR-5 dispatcher runtime MAY refine the signature (e.g. return a structured Target rather than a bare string) — GoCell carries no backward-compat burden (CLAUDE.md), so PR-5 is free to evolve this type alongside the cellgen template.

type WebhookReceiveHandler ¶

type WebhookReceiveHandler func(ctx context.Context, d Delivery) error

WebhookReceiveHandler is the inbound-webhook handler signature cellgen emits as the second argument to reg.RegisterWebhookReceiver. The runtime hands the handler a Delivery that has already been HMAC-verified and idempotency-claimed; a non-nil error signals the receiver runtime to reject (NACK) the delivery.

Handlers MUST be idempotent. The receiver's Claimer is defense-in-depth, not a sole guarantee: webhook delivery is at-least-once by nature (network retries, provider redelivery), and the dedupe window is bounded by the Claimer's done-TTL — a duplicate arriving after that window (e.g. a provider whose retry horizon exceeds the TTL) will re-invoke the handler. This matches the consumer-side guidance of Stripe / Svix, which leave deduplication to the application; GoCell additionally provides the Claimer as a framework-level best-effort layer.

PR-3: signature upgraded from func(ctx, []byte) error to func(ctx, Delivery) error in lockstep with the cellgen template and the generated method values it binds. GoCell carries no backward-compat burden (CLAUDE.md).