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.
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.mdto: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.<timestamp><separator><raw request body bytes>and the default structured-header fieldstandv1.tv1.v1values are supported for secret rotation and that any matching signature is accepted.Acceptance criteria
HmacandHeaderSecretexamples remain valid and are not presented as deprecated.webhook-route.v1.schema.json.