Documentation
¶
Overview ¶
Package whsign implements the ploykit webhook delivery signature protocol.
It is deliberately a zero-dependency leaf (stdlib only): webhook RECEIVERS — independent services that consume ploykit-originated deliveries, such as pack integrations — must be able to verify deliveries without importing the webhooks business domain or any of ploykit's transitive dependencies. The webhooks/app package delegates to this implementation, so sender and receivers share one protocol definition and can never drift apart.
Protocol (for non-Go receivers) ¶
Signature algorithm — HMAC-SHA256 over "<unixSeconds>." + rawBody, hex encoded, prefixed "sha256=":
mac := HMAC_SHA256(key = subscriptionSecret, msg = unixSeconds + "." + rawBody) header := "sha256=" + hex_lowercase(mac)
Delivery headers:
X-Signature current secret's signature (always present) X-Signature-Old previous secret's signature (present during the 24h rotation window) X-Timestamp signing time, RFC 3339 with nanoseconds X-Event-Id stable event id — receivers MUST dedupe on this X-Event-Type catalog event type X-Delivery-Id per-attempt delivery id (retry attempts get new ids — dedupe on X-Event-Id, not this)
Verification recipe:
- parse X-Timestamp; reject if |now - ts| exceeds your replay window (ploykit's own receivers use 5 minutes: RecommendedReplayWindow);
- compute the signature per the algorithm above over the RAW request body (before any decoding) with your subscription secret;
- constant-time compare against X-Signature; on failure during a rotation window, compare against X-Signature-Old (VerifyAny handles both);
- dedupe on X-Event-Id — deliveries retry with the same event id.
Index ¶
- Constants
- func Sign(secret string, timestamp time.Time, body []byte) string
- func VerifySign(secret string, timestamp time.Time, body []byte, signature string) bool
- func VerifySignAny(secrets []string, timestamp time.Time, body []byte, signature string) bool
- func VerifySignWithWindow(secret string, ts time.Time, body []byte, signature string, ...) bool
Constants ¶
const OldSecretTTL = 24 * time.Hour
OldSecretTTL is how long a rotated-out secret keeps signing (as X-Signature-Old) while receivers update: 24 hours.
const RecommendedReplayWindow = 5 * time.Minute
RecommendedReplayWindow is the clock-skew window ploykit's own receivers accept for the X-Timestamp check. Receivers may tighten or widen it, but should document whatever they choose.
Variables ¶
This section is empty.
Functions ¶
func Sign ¶
Sign returns the X-Signature value for body signed with secret at timestamp: "sha256=" + hex(HMAC-SHA256(secret, "<unixSeconds>." + body)).
func VerifySign ¶
VerifySign reports whether signature matches secret's signature for (timestamp, body), in constant time.
func VerifySignAny ¶
VerifyAny tries each secret (current first, then the old one inside the rotation window), skipping empty entries — the receiver-side counterpart of the X-Signature / X-Signature-Old dual header.
func VerifySignWithWindow ¶
func VerifySignWithWindow(secret string, ts time.Time, body []byte, signature string, maxAge time.Duration, now time.Time) bool
VerifySignWithWindow is VerifySign plus the replay check: the timestamp must be within maxAge of now in either direction. Receivers should call this (not bare VerifySign) — an untimed signature is replayable verbatim.
Types ¶
This section is empty.