signing

package
v0.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 24, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package signing implements Standard Webhooks (https://www.standardwebhooks.com) HMAC-SHA256 signature generation and verification. It mirrors packages/signing in the TypeScript implementation, which remains the source of truth for behavior and wire format.

Sign/Verify are byte-for-byte compatible with the official standardwebhooks libraries and with the TS @anyhook/signing package -- see the golden vector test in sign_test.go.

Index

Constants

View Source
const DefaultSecretBytes = 24

DefaultSecretBytes is the number of random bytes GenerateSecret encodes by default.

View Source
const SecretPrefix = "whsec_"

SecretPrefix is prepended to generated signing secrets.

View Source
const ToleranceSeconds = 300

ToleranceSeconds is the allowed clock-skew window for Verify.

Variables

This section is empty.

Functions

func GenerateSecret

func GenerateSecret(numBytes int) (string, error)

GenerateSecret generates a new Standard Webhooks-compatible signing secret: a whsec_-prefixed, base64-encoded random byte string. Pass 0 for the default (24 bytes).

func ParseSecret

func ParseSecret(secret string) ([]byte, error)

ParseSecret parses a webhook signing secret into raw HMAC key bytes. Strips the whsec_ prefix (if present) and base64-decodes the remainder.

func Sign

func Sign(secret string, id string, timestamp time.Time, payload string) (string, error)

Sign computes a single Standard Webhooks "v1,<sig>" signature.

  • secret: the signing secret (with or without the whsec_ prefix)
  • id: the webhook delivery id
  • timestamp: the delivery timestamp
  • payload: the exact raw JSON payload string

func Verify

func Verify(headers map[string]string, rawBody string, secret string) ([]byte, error)

Verify verifies a Standard Webhooks delivery and returns the raw, verified body bytes.

  • headers: the delivery headers (keys matched case-insensitively)
  • rawBody: the exact raw request body string
  • secret: the signing secret (with or without the whsec_ prefix)

Returns a *WebhookVerificationError if headers are missing, the timestamp is outside tolerance, or no signature matches.

Unlike the TS verify() (which returns the JSON.parse()'d body as `unknown`), Verify returns the raw validated bytes -- more idiomatic Go, letting the caller json.Unmarshal into whatever type it expects.

Types

type CoreSigner

type CoreSigner struct{}

CoreSigner adapts Signer to the shape of anyhook-core's WebhookSigner port (Sign(secrets []string, id, payload string, timestampMs int64) map[string]string). Package core is never imported here (by design, G1): Go's structural interface satisfaction means CoreSigner implements core.WebhookSigner purely by matching its method signature, the same "structural" trick the TS package uses to avoid a hard dependency edge on @anyhook/core.

Sign is infallible by port contract (mirrors the TS synchronous, non-throwing port): a malformed secret (e.g. invalid base64) is a configuration error that should be caught at secret-creation/rotation time, not at delivery time, so this adapter degrades to an empty signature for that entry rather than panicking or returning an error.

func (CoreSigner) Sign

func (CoreSigner) Sign(secrets []string, id string, payload string, timestampMs int64) map[string]string

Sign implements the core.WebhookSigner port shape.

type Signer

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

Signer computes Standard Webhooks delivery headers, optionally signing with multiple secrets for zero-downtime key rotation.

func NewSigner

func NewSigner(secrets ...string) *Signer

NewSigner builds a Signer over one or more secrets (space-joined in the webhook-signature header, one v1,<sig> entry per secret).

func (*Signer) Headers

func (s *Signer) Headers(id string, payload string, timestamp time.Time) (map[string]string, error)

Headers computes the webhook-id, webhook-timestamp, and webhook-signature headers.

  • id: the webhook delivery id
  • payload: the exact raw JSON payload string
  • timestamp: the delivery timestamp

type WebhookVerificationError

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

WebhookVerificationError is returned when a webhook delivery fails signature or timestamp verification.

func (*WebhookVerificationError) Error

func (e *WebhookVerificationError) Error() string

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL