webhooks

Documentation

Overview

Package webhooks verifies signed OpenSettle webhook deliveries.

The signing scheme matches the API's deliverer exactly:

header  : x-opensettle-signature: t=<unix>,v1=<hex_hmac_sha256>
message : <unix_seconds>.<raw_body>
secret  : the per-endpoint signing secret returned by
          POST /v1/workspaces/:ws/webhook_endpoints (or its
          rotation endpoint)

Verify is constant-time. It returns a typed *VerificationError on every failure path so handlers can return 400 with confidence — the request didn't come from OpenSettle.

Index

• func Decode[T any](opts Opts) (*T, int64, error)
• type Opts
• type Reason
• type VerificationError
  • func (e *VerificationError) Error() string
• type Verified
  • func Verify(opts Opts) (*Verified, error)

Functions

func Decode

func Decode[T any](opts Opts) (*T, int64, error)

Decode is a generic helper that verifies the signature, then unmarshals the body into T.

Types

type Opts

type Opts struct {
	RawBody         []byte
	SignatureHeader string
	Secret          string
	// Tolerance bounds how stale a timestamp may be. Default 5 minutes.
	// Set to 0 to disable timestamp checking entirely (not recommended
	// outside replay-driven tests).
	Tolerance time.Duration
	// Now is the reference time used for tolerance checks. Defaults to
	// time.Now. Override in tests.
	Now func() time.Time
}

Opts are the inputs Verify needs. RawBody is the exact request body bytes — verification anchors on those exact bytes, so re-marshaling the JSON before passing it in will break the signature.

type Reason

type Reason string

Reason names every distinct failure surface so handlers can branch.

const (
	ReasonMissingHeader     Reason = "missing_header"
	ReasonMalformedHeader   Reason = "malformed_header"
	ReasonStaleTimestamp    Reason = "stale_timestamp"
	ReasonSignatureMismatch Reason = "signature_mismatch"
	ReasonInvalidBody       Reason = "invalid_body"
)

type VerificationError

type VerificationError struct {
	Reason  Reason
	Message string
}

VerificationError is the only error type Verify returns. Handlers typically just respond with HTTP 400 — every reason indicates the request was not authentic.

func (*VerificationError) Error

func (e *VerificationError) Error() string

type Verified

type Verified struct {
	Body      json.RawMessage
	Timestamp int64
}

Verified wraps the decoded body alongside the timestamp the signing payload was anchored on.

func Verify

func Verify(opts Opts) (*Verified, error)

Verify checks the signature and tolerance window, returning the parsed body and timestamp on success.