Documentation
¶
Overview ¶
Package webhooks provides reusable webhook receiver and signing primitives.
It verifies raw request bodies before decoding JSON payloads, signs outbound JSON webhook requests, and leaves provider-specific event schemas, replay storage, delivery retries, and idempotency policy to application code.
Index ¶
- Variables
- func BuildSignedRequest[T any](ctx context.Context, event OutgoingEvent[T], config SignedRequestConfig) (*http.Request, error)
- func DecodeJSON[T any](body []byte) (T, error)
- func WriteProblem(w http.ResponseWriter, status int, problem httpx.Problem)
- type Event
- type HMACConfig
- type HMACSignerConfig
- type OutgoingEvent
- type Receiver
- type ReceiverConfig
- type SignatureEncoding
- type SignedRequestConfig
- type Signer
- type SignerFunc
- type Verifier
- type VerifierFunc
Constants ¶
This section is empty.
Variables ¶
var ( // ErrMissingSignature reports a request without the configured signature header. ErrMissingSignature = errors.New("missing webhook signature") // ErrInvalidSignature reports a request with a malformed or non-matching signature. ErrInvalidSignature = errors.New("invalid webhook signature") )
Functions ¶
func BuildSignedRequest ¶
func BuildSignedRequest[T any](ctx context.Context, event OutgoingEvent[T], config SignedRequestConfig) (*http.Request, error)
BuildSignedRequest builds a JSON webhook request and signs the exact request body.
func DecodeJSON ¶
DecodeJSON decodes a webhook payload as JSON.
func WriteProblem ¶
func WriteProblem(w http.ResponseWriter, status int, problem httpx.Problem)
WriteProblem writes a webhook Problem Details response.
Types ¶
type HMACConfig ¶
type HMACConfig struct {
Secret []byte
HeaderName string
Encoding SignatureEncoding
Prefix string
}
HMACConfig configures HMAC-SHA256 signature verification.
type HMACSignerConfig ¶
type HMACSignerConfig struct {
Secret []byte
Encoding SignatureEncoding
Prefix string
}
HMACSignerConfig configures HMAC-SHA256 webhook signing.
type OutgoingEvent ¶
type OutgoingEvent[T any] struct { ID string `json:"id"` Type string `json:"type,omitempty"` Payload T `json:"payload,omitempty"` }
OutgoingEvent is a JSON webhook event envelope for outbound signing helpers.
type Receiver ¶
type Receiver[T any] struct { Config ReceiverConfig[T] }
Receiver is an http.Handler for verified webhook events.
type ReceiverConfig ¶
type ReceiverConfig[T any] struct { Verifier Verifier MaxBodyBytes int64 Decode func([]byte) (T, error) Handle func(context.Context, Event[T]) error ErrorWriter func(http.ResponseWriter, int, httpx.Problem) }
ReceiverConfig configures a webhook receiver.
type SignatureEncoding ¶
type SignatureEncoding int
SignatureEncoding describes how a signature header is encoded.
const ( SignatureEncodingHex SignatureEncoding = iota SignatureEncodingBase64 SignatureEncodingBase64URL )
type SignedRequestConfig ¶
type SignedRequestConfig struct {
Method string
URL string
Signer Signer
EventID string
Timestamp time.Time
SignatureHeader string
EventIDHeader string
TimestampHeader string
ContentType string
Headers http.Header
}
SignedRequestConfig configures BuildSignedRequest.
type Signer ¶
Signer signs a raw webhook request body.
func NewHMACSHA256Signer ¶
func NewHMACSHA256Signer(config HMACSignerConfig) (Signer, error)
NewHMACSHA256Signer constructs an HMAC-SHA256 signer.
type SignerFunc ¶
SignerFunc adapts a function to Signer.
func (SignerFunc) SignWebhook ¶
SignWebhook signs a raw webhook request body.
type Verifier ¶
Verifier verifies a raw webhook request body.
func NewHMACSHA256Verifier ¶
func NewHMACSHA256Verifier(config HMACConfig) (Verifier, error)
NewHMACSHA256Verifier constructs an HMAC-SHA256 verifier.
type VerifierFunc ¶
VerifierFunc adapts a function to Verifier.
func (VerifierFunc) VerifyWebhook ¶
VerifyWebhook verifies a raw webhook request body.