Skip to content

docs(configuration): document timestamped-HMAC webhook verification #84

Description

@Aaronontheweb

Context

Netclaw issue netclaw-dev/netclaw#1658 adds an explicit timestamped-HMAC webhook verification mode while retaining the existing body-HMAC and header-secret modes.

The website currently documents only the legacy verification behavior. Update it once the Netclaw implementation ships.

Scope

Update src/content/docs/configuration/webhooks.md to:

  • Document all three verification modes and when to choose each:
    • Hmac — existing HMAC over the raw request body; remains the default for backward compatibility.
    • HeaderSecret — existing direct shared-secret comparison.
    • HmacTimestamped — structured signature header plus replay-window enforcement.
  • State explicitly that the modes are independent. Netclaw does not automatically migrate existing routes and does not fall back from timestamped verification to a legacy verifier.
  • Document timestamped signing as <timestamp><separator><raw request body bytes> and the default structured-header fields t and v1.
  • Document the default timestamped settings:
    • tolerance: 300 seconds
    • timestamp field: t
    • signature field: v1
    • signed-payload separator: .
  • Explain that multiple v1 values are supported for secret rotation and that any matching signature is accepted.
  • Add Stripe-style and TextForge-style JSON route examples, including custom header/field names where appropriate.
  • Add troubleshooting guidance for raw-body mismatches, stale/future timestamps, malformed signature headers, and clock skew.
  • Link back to the CLI webhook documentation.

Acceptance criteria

  • Existing Hmac and HeaderSecret examples remain valid and are not presented as deprecated.
  • Property names and defaults match the released webhook-route.v1.schema.json.
  • The page clearly distinguishes authentication from replay protection.
  • Examples can be copied into a current Netclaw configuration without schema or runtime validation errors.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions