sxsphinxstack

Skills / Starter / Verify a webhook signature

Starter Code skill

Verify a webhook signature

Verify a webhook signature over exact bytes with trusted key selection, timestamp tolerance, replay protection, and rotation support.

When to use

  • Use before parsing or acting on a signed delivery.
  • Never log secrets, full sensitive payloads, or accepted replay material.

Preconditions

  • Obtain the provider specification, secret or public keys, raw-body access, clock policy, and event identity.

Procedure

  1. Capture exact request bytes and required signed headers before transformation.
  2. Parse signature versions and key IDs using strict bounds.
  3. Select only trusted algorithms and active or rotation-overlap keys.
  4. Reconstruct the signed message exactly and compare signatures in constant time.
  5. Validate timestamp and durable event replay state.
  6. Reject before side effects and test rotation, duplicates, stale delivery, malformed input, and body mutation.

Failure plan

  • Fail closed when raw bytes, key state, algorithm, or replay storage are unavailable.

Worked example

A valid signature over a stale timestamp is rejected and the event ID remains unprocessed.

Related skills

  • Verify a feature flag state — Verify a feature flag state for a specific subject, environment, version, time, rule set, and evaluation path.
  • Write a unit test — Write a focused deterministic unit test that specifies one behavior, boundary, failure, or invariant with useful diagnostics.
  • Validate untrusted input — Validate untrusted input at a system boundary with explicit schemas, limits, normalization, and safe errors.