webhooks

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
  • func (receiver Receiver[T]) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type ReceiverConfig
• type SignatureEncoding
• type SignedRequestConfig
• type Signer
  • func NewHMACSHA256Signer(config HMACSignerConfig) (Signer, error)
• type SignerFunc
  • func (f SignerFunc) SignWebhook(ctx context.Context, body []byte) (string, error)
• type Verifier
  • func NewHMACSHA256Verifier(config HMACConfig) (Verifier, error)
• type VerifierFunc
  • func (f VerifierFunc) VerifyWebhook(ctx context.Context, r *http.Request, body []byte) error

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

func DecodeJSON[T any](body []byte) (T, error)

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 Event

type Event[T any] struct {
	Payload T
	RawBody []byte
	Request *http.Request
}

Event is a verified and decoded webhook event.

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.

func (Receiver[T]) ServeHTTP

func (receiver Receiver[T]) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP verifies, decodes, and accepts a webhook event.

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

type Signer interface {
	SignWebhook(ctx context.Context, body []byte) (string, error)
}

Signer signs a raw webhook request body.

func NewHMACSHA256Signer

func NewHMACSHA256Signer(config HMACSignerConfig) (Signer, error)

NewHMACSHA256Signer constructs an HMAC-SHA256 signer.

type SignerFunc

type SignerFunc func(context.Context, []byte) (string, error)

SignerFunc adapts a function to Signer.

func (SignerFunc) SignWebhook

func (f SignerFunc) SignWebhook(ctx context.Context, body []byte) (string, error)

SignWebhook signs a raw webhook request body.

type Verifier

type Verifier interface {
	VerifyWebhook(ctx context.Context, r *http.Request, body []byte) error
}

Verifier verifies a raw webhook request body.

func NewHMACSHA256Verifier

func NewHMACSHA256Verifier(config HMACConfig) (Verifier, error)

NewHMACSHA256Verifier constructs an HMAC-SHA256 verifier.

type VerifierFunc

type VerifierFunc func(context.Context, *http.Request, []byte) error

VerifierFunc adapts a function to Verifier.

func (VerifierFunc) VerifyWebhook

func (f VerifierFunc) VerifyWebhook(ctx context.Context, r *http.Request, body []byte) error

VerifyWebhook verifies a raw webhook request body.