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
- func GenerateSecret(numBytes int) (string, error)
- func ParseSecret(secret string) ([]byte, error)
- func Sign(secret string, id string, timestamp time.Time, payload string) (string, error)
- func Verify(headers map[string]string, rawBody string, secret string) ([]byte, error)
- type CoreSigner
- type Signer
- type WebhookVerificationError
Constants ¶
const DefaultSecretBytes = 24
DefaultSecretBytes is the number of random bytes GenerateSecret encodes by default.
const SecretPrefix = "whsec_"
SecretPrefix is prepended to generated signing secrets.
const ToleranceSeconds = 300
ToleranceSeconds is the allowed clock-skew window for Verify.
Variables ¶
This section is empty.
Functions ¶
func GenerateSecret ¶
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 ¶
ParseSecret parses a webhook signing secret into raw HMAC key bytes. Strips the whsec_ prefix (if present) and base64-decodes the remainder.
func Sign ¶
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 ¶
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.
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 ¶
NewSigner builds a Signer over one or more secrets (space-joined in the webhook-signature header, one v1,<sig> entry per secret).
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