Documentation
¶
Overview ¶
Package hooks provides shared Standard Webhooks construction helpers and wiring for go-service.
This package integrates the Standard Webhooks Go library (github.com/standard-webhooks/standard-webhooks/libraries/go) by providing:
configuration for the named webhook secret set used by Standard Webhooks signers/verifiers (see Config), loaded via the go-service "source string" pattern (resolved by github.com/alexfalkowski/go-service/v2/os.FS.ReadSource), and
constructors for creating Standard Webhooks hooks (see NewHook) and generating new secrets (see Generator).
Secrets and source strings ¶
Each value in Config.Secrets is a "source string" and may be:
- "env:NAME" to read the secret from an environment variable,
- "file:/path/to/secret" to read the secret from a file, or
- any other value treated as the literal secret.
The resolved secret bytes are passed to the Standard Webhooks library as a string. Empty resolved secrets are rejected by this package, while non-empty secrets must use a format accepted by the Standard Webhooks constructor. The Generator output is accepted directly as a literal secret. Keep this value private and avoid logging it.
Config.Key selects the active entry in Config.Secrets used for signing. Verification accepts signatures from every configured secret because Standard Webhooks signs a message id, timestamp, and payload, but does not include a signing key id that could select one secret directly.
Downstream integrations ¶
Transport integrations (for example github.com/alexfalkowski/go-service/v2/transport/http/hooks) build on top of this package to verify incoming webhook signatures and/or sign outbound webhook requests.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrEmptySecret = errors.New("hooks: empty secret")
ErrEmptySecret indicates that webhook secret configuration resolved to empty bytes.
var ErrInvalidConfig = errors.New("hooks: invalid config")
ErrInvalidConfig indicates webhook secret rotation configuration is incomplete.
var Module = di.Module( di.Constructor(NewGenerator), di.Constructor(NewHook), )
Module wires shared Standard Webhooks helpers into go.uber.org/fx/go.uber.org/dig.
It provides constructors for:
- *Generator (via NewGenerator), which generates new secret values suitable for Standard Webhooks, and
- *Hook (via NewHook), which constructs a signer/verifier from configuration.
Disabled behavior: if hooks configuration is disabled (nil *Config), NewHook returns (nil, nil) so downstream consumers can treat webhook verification/signing as optional.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// Secrets contains named Standard Webhooks secrets trusted for verification.
//
// Key selects the active secret used for signing.
// Verification accepts signatures from every configured secret.
Secrets Secrets `yaml:"secrets,omitempty" json:"secrets,omitempty" toml:"secrets,omitempty"`
// Key is the active secret id used for signing.
//
// The selected entry must exist in Secrets.
Key string `yaml:"key,omitempty" json:"key,omitempty" toml:"key,omitempty"`
// Leeway is the optional clock-skew tolerance applied to the Webhook-Timestamp
// freshness check during verification.
//
// A zero value keeps the Standard Webhooks library's fixed 5-minute freshness
// window. A non-zero value replaces that fixed window with this configured
// tolerance, matching the clock-skew Leeway already exposed by the JWT,
// PASETO, and SSH token verifiers.
Leeway time.Duration `yaml:"leeway,omitempty" json:"leeway,omitempty" toml:"leeway,omitempty" validate:"omitempty,duration_second_precision"`
}
Config configures Standard Webhooks secret loading.
type Generator ¶
type Generator struct {
// contains filtered or unexported fields
}
Generator generates secret values suitable for Standard Webhooks.
func NewGenerator ¶
NewGenerator constructs a Generator for creating Standard Webhooks secrets.
The returned Generator uses a cryptographically-secure random generator.
func (*Generator) Generate ¶
Generate returns a new base64-encoded Standard Webhooks secret string.
It generates 32 random bytes and encodes them using standard base64. The returned string can be used as a literal value in Config.Secrets. If the underlying random generator fails, Generate returns that error.
type Hook ¶ added in v2.636.0
type Hook struct {
// contains filtered or unexported fields
}
Hook signs and verifies Standard Webhooks signatures.
A Hook has one active signer and one or more trusted verifiers. This supports secret rotation by signing with the active configured secret while accepting signatures from the full configured secret set.
func NewHook ¶ added in v2.73.0
NewHook constructs a Standard Webhooks hook from cfg.
Disabled behavior: if cfg is nil/disabled, NewHook returns (nil, nil).
Enabled behavior: NewHook resolves Config.Secrets and constructs Standard Webhooks instances using those secrets. Source-resolution errors and Standard Webhooks constructor errors are returned to the caller.
Secret encoding expectations: The secret bytes are converted to a string and passed to the Standard Webhooks library. In typical setups this string is the base64-encoded secret generated by Generator.Generate, with or without the Standard Webhooks `whsec_` prefix, but NewHook does not enforce a particular encoding beyond what the downstream library expects. Empty resolved secrets are rejected with ErrEmptySecret.
func (*Hook) Sign ¶ added in v2.636.0
Sign computes a Standard Webhooks signature with the active secret.
func (*Hook) Verify ¶ added in v2.636.0
Verify verifies payload and headers against the configured trusted secrets.
When Config.Leeway is zero, the Webhook-Timestamp freshness check uses the Standard Webhooks library's fixed 5-minute window. When Config.Leeway is non-zero, Verify checks Webhook-Timestamp against that configured window itself, then verifies the signature ignoring the library's own timestamp check.
Source Files