feat(webhooks): add timestamped HMAC verification#1660
Merged
Aaronontheweb merged 11 commits intoJul 16, 2026
Conversation
Aaronontheweb
added
webhooks
There was a problem hiding this comment.
Pull request overview
This PR adds an explicit, opt-in HmacTimestamped webhook verifier (Stripe-style t=...,v1=...) with replay tolerance enforcement, exposes the new verifier across route config + CLI + tools + schemas + ops guidance, and improves determinism/cancellation semantics in daemon restart drain flows.
Changes:
- Add
WebhookVerifierKind.HmacTimestampedverification: structured header parsing, rotation signatures support, and timestamp replay-tolerance enforcement usingTimeProvider. - Extend configuration + validation + JSON schemas + CLI/tool surfaces (including eval coverage) to support timestamped verification settings while preserving legacy route behavior.
- Harden route persistence updates for concurrent writers (interprocess route-scoped lock) and make restart-drain tests deterministic via causal synchronization and virtual time.
Reviewed changes
Copilot reviewed 32 out of 32 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| src/Netclaw.Daemon/Webhooks/WebhookRequestVerifier.cs | Adds timestamped-HMAC verification branch with tolerance enforcement. |
| src/Netclaw.Daemon/Webhooks/RegisteredWebhookRoute.cs | Adds effective-default accessors for timestamped verification settings. |
| src/Netclaw.Daemon/Services/SessionDrainHelper.cs | Splits cancellation tokens to distinguish deadline timeout vs caller cancellation; adds drain-ack log event. |
| src/Netclaw.Daemon/Services/DaemonRestartCoordinator.cs | Uses virtual time for drain deadline CTS and passes separate cancellation tokens to drain helper. |
| src/Netclaw.Daemon/Program.cs | Updates drain helper call site; registers verifier via DI. |
| src/Netclaw.Daemon.Tests/Webhooks/WebhookRouteCatalogTests.cs | Adds tests ensuring unknown/future verifier kinds only invalidate the affected route. |
| src/Netclaw.Daemon.Tests/Webhooks/WebhookRequestVerifierTests.cs | Adds unit coverage for timestamped-HMAC: defaults, rotation, custom fields, tolerance boundaries, malformed headers. |
| src/Netclaw.Daemon.Tests/Webhooks/WebhookEndpointRouteBuilderExtensionsTests.cs | Adds endpoint-level tests for timestamped signature acceptance/rejection without dispatch on stale timestamps. |
| src/Netclaw.Daemon.Tests/Services/DaemonRestartCoordinatorTests.cs | Refactors restart-drain tests to be deterministic using FakeTimeProvider and explicit ack coordination. |
| src/Netclaw.Configuration/WebhooksConfig.cs | Adds optional timestamped verification fields and new enum value. |
| src/Netclaw.Configuration/WebhookRouteValidator.cs | Adds enum validation, timestamped-specific validation, and CLI/tool kind parsing helper. |
| src/Netclaw.Configuration/WebhookRouteStore.cs | Introduces route-scoped interprocess locking + atomic write strategy; adds Update API and cancellable Delete. |
| src/Netclaw.Configuration/Schemas/webhook-route.v1.schema.json | Extends route schema for timestamped verification fields + conditional constraints. |
| src/Netclaw.Configuration/Schemas/netclaw-config.v1.schema.json | Extends embedded config schema for timestamped verification fields + conditional constraints. |
| src/Netclaw.Configuration.Tests/WebhookRouteStoreTests.cs | Adds coverage for legacy round-trip behavior, timestamped validation, schema parity, and concurrent Update serialization. |
| src/Netclaw.Cli/Webhooks/WebhooksCommand.cs | Adds timestamped verifier support in list/show/set/validate output + arguments; uses route store Update for atomic updates. |
| src/Netclaw.Cli.Tests/Webhooks/WebhooksCommandTests.cs | Adds CLI tests for timestamped persistence, validation failures, output shape, and schema evaluation. |
| src/Netclaw.Actors/Tools/SetWebhookTool.cs | Extends set_webhook tool schema + persistence to support timestamped options and preserve omitted settings under store lock. |
| src/Netclaw.Actors/Tools/DeleteWebhookTool.cs | Updates deletion to use cancellable store delete with timeout handling. |
| src/Netclaw.Actors.Tests/Tools/SetWebhookToolProvenanceTests.cs | Adds tests for timestamped options persistence, rejection rules, and update-preserves-omitted-settings behavior. |
| openspec/specs/inbound-webhooks/spec.md | Updates capability spec to include timestamped-HMAC verification and related requirements/scenarios. |
| openspec/changes/add-timestamped-webhook-hmac/tasks.md | Adds OpenSpec task checklist for the change. |
| openspec/changes/add-timestamped-webhook-hmac/specs/inbound-webhooks/spec.md | Adds delta spec describing modified/added requirements for timestamped-HMAC. |
| openspec/changes/add-timestamped-webhook-hmac/proposal.md | Documents motivation, scope, compatibility, and impact for the change. |
| openspec/changes/add-timestamped-webhook-hmac/design.md | Documents design decisions, constraints, and trade-offs. |
| openspec/changes/add-timestamped-webhook-hmac/.openspec.yaml | Declares OpenSpec change metadata. |
| feeds/skills/.system/files/netclaw-operations/SKILL.md | Bumps operations skill version. |
| feeds/skills/.system/files/netclaw-operations/references/webhooks.md | Adds operator guidance for timestamped-HMAC selection and configuration. |
| evals/run-evals.sh | Adds eval asserting set_webhook usage for Stripe timestamped verification. |
| evals/README.md | Updates eval suite expectations to include timestamped webhook configuration. |
| evals/fixtures/config/netclaw.json | Enables Webhooks.Enabled in eval fixture config. |
| docs/spec/configuration.md | Documents timestamped verifier usage and exposes new route verification fields. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Aaronontheweb
commented
Jul 16, 2026
Aaronontheweb
left a comment
Aaronontheweb
left a comment
Collaborator
Author
There was a problem hiding this comment.
LGTM - going to test this out in the beta lane with a real webhook origin
| if (!Enum.IsDefined(route.Verification.HmacAlgorithm)) | ||
| errors.Add($"Verification.HmacAlgorithm value '{(int)route.Verification.HmacAlgorithm}' is not supported."); | ||
|
|
||
| if (route.Verification.Kind == WebhookVerifierKind.HmacTimestamped) |
Collaborator
Author
There was a problem hiding this comment.
new feature we're adding here
This was referenced Jul 16, 2026
Merged
Merged
Closed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Backward compatibility
Validation
Documentation follow-ups
Closes #1658