Skip to content

docs(cli): document hmac-timestamped webhook flags and examples #85

Description

@Aaronontheweb

Context

Netclaw issue netclaw-dev/netclaw#1658 adds hmac-timestamped as an explicit webhook verification mode and extends netclaw webhooks with timestamp-verification options.

The CLI documentation needs to describe the new surface while making the compatibility policy clear.

Scope

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

  • Add hmac-timestamped to the accepted --verification-kind values.
  • Document these webhooks set options:
    • --timestamp-field
    • --signature-field
    • --signed-payload-separator
    • --signature-tolerance-seconds
  • Add a complete Stripe-style command using Stripe-Signature.
  • Show the equivalent webhooks show human and JSON output, including effective defaults.
  • Explain that timestamp-specific options are rejected unless the route uses hmac-timestamped.
  • Keep hmac documented as the default for omitted --verification-kind; do not describe legacy modes as deprecated.
  • Document the accepted header-secret spelling and remove any warning that it fails to parse once the supporting Netclaw release is available.
  • Add examples for updating an existing legacy route without changing its verification mode and for explicitly migrating a route after its sender is reconfigured.
  • Explain the relevant failure behavior: invalid configuration is rejected before persistence, and invalid/stale deliveries receive 401 without dispatch.

Acceptance criteria

  • Every documented command matches the released CLI help and executes successfully against a temporary config.
  • Defaults match the configuration reference and schema.
  • Migration is presented as an explicit per-route operator action, not an automatic upgrade.
  • The page links to the webhook configuration reference for protocol-level signing details.

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