webhook-server/PLAN.md

Windows Webhook Server — Implementation Plan

Context

Greenfield project at /Users/justin/GitHub/webhook-server (currently empty). Goal: a Windows-native webhook server that receives HTTP requests and runs PowerShell, PowerShell Core, cmd/.bat, or arbitrary executables in response. Each webhook is configured in a desktop GUI; the actual server runs as a Windows Service so it survives reboots and works without anyone logged in. Auth is per-endpoint (HMAC, bearer, or none) so it can sit behind a CI system, a smart-home hub, GitHub webhooks, etc.

Note: Build/test machine must be Windows. The current dev host is macOS — final verification needs a Windows VM or box.

Architecture summary

Two processes, one config:

┌──────────────────┐  named pipe   ┌──────────────────────────────┐
│   WPF GUI app    │ ◄──────────► │  Windows Service              │
│  (config/monitor)│               │  ├─ Kestrel: webhook listener│
└──────────────────┘               │  ├─ Named-pipe admin server  │
                                   │  ├─ Executor pool            │
                                   │  └─ Serilog file logging     │
                                   └──────────────────────────────┘
                                            ▲
                            C:\ProgramData\WebhookServer\
                            ├─ config.json   (DPAPI-encrypted secrets)
                            └─ logs\*.log

• WebhookServer.Service — .NET 8 Worker Service. Hosts an embedded Kestrel WebApplication for webhook traffic, plus a named-pipe server for the GUI. Single source of truth.
• WebhookServer.Gui — WPF (.NET 8) MVVM app. Thin client over the named pipe. Edits endpoints, shows live status/logs, can start/stop the service.
• WebhookServer.Core — class library shared by both. Config schema, executor abstraction, auth verifiers, IPC contracts, DPAPI helpers.

Tech choices (locked from clarifying Qs)

Concern	Choice
Stack	C# / .NET 8 + WPF
Endpoints	Multiple, each at its own URL slug
Auth	Per-endpoint pick: HMAC / bearer token / none
Run mode	Service-first; GUI is config/monitor only
Script types	Windows PowerShell, PowerShell Core, cmd/.bat, arbitrary exe
Data passing	Any combination of: JSON body → stdin, query/headers → env vars, arg template {{...}}
Response	Per-endpoint sync (exit code + stdout/stderr) or async (202 immediate)
GUI ↔ service	Named pipe \\.\pipe\WebhookServerAdmin (JSON over line-delimited frames)
HTTPS	HTTP default; GUI can bind a cert (.pfx path or cert-store thumbprint)
Secrets	DPAPI LocalMachine scope — encrypted at rest in config.json
Concurrency	Parallel by default; per-endpoint "serialize" flag forces a queue
IP allowlist	Per-endpoint list of IPs and CIDR subnets; empty = all allowed; checked before auth
Outbound callbacks	Optional per-endpoint callback URL; service POSTs run result after async runs (and optionally after sync). Pre-configured only — no caller-supplied URLs.

Solution layout

webhook-server/
├─ WebhookServer.sln
├─ src/
│  ├─ WebhookServer.Core/         (netstandard2.0 or net8.0 class lib)
│  │   ├─ Models/
│  │   │   ├─ EndpointConfig.cs
│  │   │   ├─ AuthMode.cs           (None | Bearer | Hmac)
│  │   │   ├─ ExecutorType.cs       (WindowsPowerShell | PwshCore | Cmd | Executable)
│  │   │   ├─ ResponseMode.cs       (Sync | Async)
│  │   │   ├─ DataPassingOptions.cs (StdinJson, EnvVars, ArgTemplate flags + template string)
│  │   │   ├─ AllowedClient.cs      (single IP or CIDR string, validated)
│  │   │   └─ ServerConfig.cs       (HttpPort, HttpsBinding, TrustedProxies[], AdminToken, Endpoints[])
│  │   ├─ Auth/
│  │   │   ├─ IAuthVerifier.cs
│  │   │   ├─ BearerVerifier.cs
│  │   │   ├─ HmacVerifier.cs        (configurable header + sha1/sha256/sha512)
│  │   │   └─ IpAllowList.cs         (parse + match IP / CIDR, IPv4 + IPv6)
│  │   ├─ Execution/
│  │   │   ├─ IExecutor.cs           (RunAsync(ctx) → ExecutionResult)
│  │   │   ├─ ProcessExecutor.cs     (single impl, varies argv per ExecutorType)
│  │   │   ├─ ArgTemplateRenderer.cs ({{body.x}}, {{header.X-Foo}}, {{query.bar}})
│  │   │   └─ ConcurrencyGate.cs     (per-endpoint SemaphoreSlim when serialize=true)
│  │   ├─ Callbacks/
│  │   │   ├─ CallbackConfig.cs      (Url, Method, AuthMode, Secret, retry/timeout)
│  │   │   ├─ CallbackDispatcher.cs  (background queue, retry w/ exponential backoff + jitter)
│  │   │   └─ CallbackPayload.cs     (runId, endpoint, exitCode, stdout/stderr, timings)
│  │   ├─ Storage/
│  │   │   ├─ ConfigStore.cs         (load/save JSON, atomic write)
│  │   │   └─ DpapiSecret.cs         (Protect/Unprotect LocalMachine)
│  │   └─ Ipc/
│  │       ├─ AdminProtocol.cs       (request/response DTOs)
│  │       └─ PipeSecurityFactory.cs (SYSTEM + Administrators ACL)
│  ├─ WebhookServer.Service/        (.NET 8 Worker)
│  │   ├─ Program.cs                  (Host.CreateApplicationBuilder + UseWindowsService)
│  │   ├─ WebhookHost.cs              (BackgroundService that owns the WebApplication)
│  │   ├─ WebhookRouter.cs            (maps slug → endpoint, runs auth, builds context, dispatches)
│  │   ├─ AdminPipeServer.cs          (BackgroundService listening on the named pipe)
│  │   └─ appsettings.json            (only logging defaults — no endpoint config here)
│  └─ WebhookServer.Gui/             (WPF, .NET 8)
│      ├─ App.xaml(.cs)
│      ├─ MainWindow.xaml(.cs)        (endpoint list + log tail)
│      ├─ Views/EndpointEditor.xaml   (per-endpoint edit form)
│      ├─ Views/ServerSettings.xaml   (port, HTTPS cert, install/uninstall service)
│      ├─ ViewModels/                  (CommunityToolkit.Mvvm)
│      └─ Services/AdminPipeClient.cs (talks to AdminPipeServer)
└─ scripts/
   ├─ install-service.ps1            (sc.exe create WebhookServer binPath= ... start= auto)
   └─ uninstall-service.ps1

Key NuGet packages

• Microsoft.Extensions.Hosting, Microsoft.Extensions.Hosting.WindowsServices
• Microsoft.AspNetCore.App framework reference (Kestrel + minimal API routing)
• System.Security.Cryptography.ProtectedData (DPAPI)
• Serilog.AspNetCore, Serilog.Sinks.File, Serilog.Sinks.Async
• CommunityToolkit.Mvvm (GUI)

Webhook request flow

1. Kestrel receives POST /hook/{slug}.
2. Router looks up endpoint by slug. 404 if missing or disabled.
3. IP allowlist check (before any expensive work):
   • Resolve the effective client IP: HttpContext.Connection.RemoteIpAddress, then if that IP is in the server-level TrustedProxies list, take the leftmost entry from X-Forwarded-For instead. Default TrustedProxies is empty, so by default X-Forwarded-For is ignored.
   • If the endpoint's AllowedClients list is non-empty and the effective IP doesn't match any entry → 403 (no body, log the rejection).
   • Empty AllowedClients = allow all.
4. Capture raw body bytes (needed for HMAC). Buffer with EnableBuffering() or read to byte[].
5. Run the endpoint's auth verifier:
   • None → pass.
   • Bearer → compare Authorization: Bearer <secret> (constant-time compare).
   • Hmac → compute HMAC of raw body with configured algo + secret, compare against configured header (default X-Hub-Signature-256). Constant-time compare.
   • Fail → 401.
6. Build ExecutionContext: { body (string + JsonNode), headers, query, route }.
7. Acquire concurrency gate (no-op if not serialized).
8. Build ProcessStartInfo:
   • WindowsPowerShell → powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -File "<path>" or -Command "<inline>".
   • PwshCore → pwsh.exe ... (same flags).
   • Cmd → cmd.exe /c "<command-or-batfile>".
   • Executable → user-supplied exe path + args.
   • Apply data-passing options (any combination):
     • StdinJson → write request body to stdin, close stdin.
     • EnvVars → for each query param WEBHOOK_QUERY_<KEY>=value; for each header WEBHOOK_HEADER_<KEY>=value (sanitize key chars).
     • ArgTemplate → render template, append rendered tokens to argv.
9. Dispatch:
   • Sync mode: await process exit (with Timeout cancellation token). Return 200 (or 502 on non-zero exit, configurable) with body { exitCode, stdout, stderr, durationMs }.
   • Async mode: fire-and-forget Task; return 202 Accepted with { runId }. Output goes to log + visible in GUI.
10. Outbound callback (if configured for this endpoint): enqueue a CallbackPayload to CallbackDispatcher. For async endpoints this is the only way the original caller can learn the result. For sync endpoints it's optional (off by default) and useful for fan-out / audit sinks.
11. Always log: timestamp, slug, effective client IP, IP-allowlist result, auth result, exit code, duration, stdout/stderr (truncated), callback delivery status. Serilog → daily rolling file.

Argument template syntax

Simple {{path}} substitution. Path grammar:

• {{body.foo.bar}} — JSON path into body (uses JsonNode).
• {{header.X-GitHub-Event}} — header by name (case-insensitive).
• {{query.ref}} — query param.
• {{route.slug}} — route values.

Missing paths render as empty string. Each {{...}} becomes one argv token (already-quoted handling done by ProcessStartInfo.ArgumentList). No expression evaluation — keep it dumb so it can't be a sandbox escape vector.

Outbound callbacks

Each endpoint optionally has a Callback block. When present, the service POSTs the run result to a pre-configured URL after the script finishes. Required for async endpoints if the caller wants to know what happened; optional for sync endpoints (where the result is already returned in the HTTP response).

CallbackConfig fields:

• Url — full URL the dispatcher POSTs to.
• Method — default POST (allow PUT for systems that prefer it).
• AuthMode — None | Bearer | Hmac. Mirrors the inbound auth design — same code paths reused.
• Secret — DPAPI-encrypted (bearer token, or HMAC shared secret).
• HmacAlgorithm / HmacHeaderName / HmacPrefix / HmacEncoding — when AuthMode = Hmac. Defaults match the inbound HMAC defaults so a sender that accepts GitHub-style signatures works out of the box.
• TimeoutSeconds — default 30.
• MaxAttempts — default 5. Backoff is exponential (1s, 2s, 4s, 8s, 16s) with ±25% jitter.
• IncludeStdout / IncludeStderr — default true. Allow turning off for endpoints whose output is sensitive or huge. Truncation cap (MaxOutputBytes, default 64KB) applies regardless.
• Trigger — OnComplete (default — fires whether script succeeded or failed) | OnSuccess | OnFailure.

Payload shape (application/json; charset=utf-8):

{
  "runId": "8f4e...",
  "endpoint": "deploy",
  "startedAt": "2026-05-07T18:22:11.103Z",
  "completedAt": "2026-05-07T18:22:13.811Z",
  "durationMs": 2708,
  "exitCode": 0,
  "succeeded": true,
  "stdout": "...",
  "stderr": "",
  "stdoutTruncated": false,
  "stderrTruncated": false
}

When AuthMode = Hmac, the HMAC is computed over the raw serialized JSON body bytes with the configured algorithm and added as the configured header (e.g. X-Hub-Signature-256: sha256=...).

CallbackDispatcher:

• Single BackgroundService with a bounded Channel<CallbackPayload> queue (default capacity 1024; overflow drops oldest with a warning log).
• Uses a singleton HttpClient (no per-request allocation, follows redirects only on 3xx-with-Location for safety).
• Per-attempt timeout = TimeoutSeconds. Total deadline = MaxAttempts * (TimeoutSeconds + max-backoff).
• Retries on network failure, 408, 425, 429, 5xx. Honors Retry-After if present, capped at 60s.
• All attempts logged: outbound URL, status code, attempt number, latency, final disposition (delivered / dropped / gave-up).
• GUI surfaces a per-endpoint counter: pending / delivered / failed in last hour.

No caller-supplied callback URLs. The endpoint config is the only source. Accepting a ?callback= parameter from the request would turn the server into an SSRF gadget — easy to point at internal admin endpoints or cloud-metadata services. Callers who need dynamic fan-out can configure multiple endpoints, or run a small dispatcher script themselves.

IP allowlist details

Each endpoint has an AllowedClients: string[] field. Each entry is one of:

• Single IPv4 address — 192.168.50.20
• Single IPv6 address — fe80::1
• IPv4 CIDR — 10.10.1.0/24
• IPv6 CIDR — fd00::/8

Empty list = allow all (matches the user's default-open requirement). Any non-empty list switches that endpoint to deny-by-default.

Implementation:

• IpAllowList parses entries on config load; validation errors are surfaced in the GUI before save.
• Use System.Net.IPNetwork (added in .NET 8) for CIDR parse + Contains(IPAddress) matching. No third-party lib needed.
• Match IPv4-mapped IPv6 (::ffff:1.2.3.4) against IPv4 entries by normalizing with IPAddress.MapToIPv4() before the check.
• A server-level TrustedProxies list (also IPs/CIDRs) controls whether X-Forwarded-For / X-Real-IP is honored. If the direct connection comes from a trusted proxy, walk X-Forwarded-For from rightmost-trusted leftward and use the first untrusted IP. Otherwise ignore forwarded headers — important so callers can't spoof their IP by adding a header.
• Default TrustedProxies is empty (most secure). GUI surfaces it under server settings with a note about reverse-proxy setups.
• Rejections are logged and counted per-endpoint so the GUI can surface "blocked: 47 in last hour" — useful for catching misconfigured callers.

Order in the request pipeline matters: IP check runs before auth. That avoids HMAC compute work on blocked IPs and prevents any timing-based information leak about token validity to non-allowed sources.

Auth details

• Bearer: secret is the token itself. Verify Authorization: Bearer <secret>. Fixed-time CryptographicOperations.FixedTimeEquals.
• HMAC: configurable per endpoint:
  • Algorithm: SHA1 / SHA256 (default) / SHA512
  • HeaderName: default X-Hub-Signature-256
  • Prefix: default sha256= (stripped before compare)
  • Encoding: hex (default) or base64
  • Compute HMAC over raw body bytes with secret. Fixed-time compare.

This covers GitHub, Stripe, Slack, generic CI patterns by tweaking the four fields.

Service account

The service itself runs fine under any account — this section is about which account makes sense for the scripts the service launches, since they inherit its identity.

Account	Network identity	When to use
LocalSystem (default)	Computer account DOMAIN\MACHINE$ on a domain-joined host; nothing on a workgroup host	Default. Local-only scripts, or read-only AD queries on a domain-joined machine. Most powerful local account — any webhook script effectively runs as SYSTEM.
LocalService	None — no network credentials	Don't. Cannot talk to AD or any other remote resource that requires Windows auth. Listed only to rule it out.
NetworkService	Computer account, same as LocalSystem	Slightly less local privilege than LocalSystem; same network identity. Rarely worth the switch.
Domain user (DOMAIN\svc-webhookserver)	That user	Need write/admin operations against AD (password resets, group changes, OU creates). You own password rotation.
gMSA (DOMAIN\svc-webhookserver$)	That gMSA	Recommended for AD-write workloads. AD generates and rotates the password automatically. Requires domain functional level 2012+ and Install-ADServiceAccount on the host.

Install commands by account type:

# LocalSystem (default)
sc.exe create WebhookServer binPath= "C:\path\WebhookServer.Service.exe" start= auto

# Domain user
sc.exe create WebhookServer binPath= "..." obj= "DOMAIN\svc-webhookserver" password= "..." start= auto

# gMSA — note the trailing $ and no password=
sc.exe create WebhookServer binPath= "..." obj= "DOMAIN\svc-webhookserver$" start= auto

scripts/install-service.ps1 will accept a -ServiceAccount parameter that defaults to LocalSystem and accepts a domain user or gMSA name. README will document the gMSA setup once for users who need AD writes from their hooks.

The service code itself makes no assumptions about the account — DPAPI uses LocalMachine scope so secret decryption works under any local identity.

Secret storage (DPAPI)

Endpoint Secret is stored in JSON as { "encrypted": "<base64 of ProtectedData.Protect(utf8(secret), null, LocalMachine)>" }. Decrypt only inside the service when needed. The GUI submits secrets in plaintext over the named pipe (local-machine, ACL-restricted), service encrypts before writing.

Caveat to call out in the GUI: DPAPI LocalMachine ties config to the machine — backing up config to another box won't decrypt. Document Export Config in GUI later as a future feature.

GUI ↔ Service IPC

Named pipe \\.\pipe\WebhookServerAdmin, ACL: NT AUTHORITY\SYSTEM + BUILTIN\Administrators full control, deny everyone else. (GUI must run elevated — note that in the README.)

Protocol: line-delimited JSON request/response.

// request
{ "op": "list-endpoints" }
// response
{ "ok": true, "endpoints": [...] }

Ops needed: get-config, update-config, list-endpoints, create-endpoint, update-endpoint, delete-endpoint, enable/disable-endpoint, tail-logs (streaming), get-status, bind-https, restart-listener.

HTTPS binding

GUI offers two ways to provide a cert:

1. Path to .pfx + password (password DPAPI-encrypted in config).
2. Local cert-store thumbprint (CurrentUser\My or LocalMachine\My).

Service builds Kestrel with both an HTTP and HTTPS endpoint when bound. Restarting the listener picks up new bindings without restarting the whole service.

Critical files to be created

• src/WebhookServer.Core/Models/EndpointConfig.cs — central data shape
• src/WebhookServer.Core/Auth/HmacVerifier.cs — must use raw body + fixed-time compare
• src/WebhookServer.Core/Auth/IpAllowList.cs — IPv4/IPv6 + CIDR matching, IPv4-mapped IPv6 normalization, runs before auth
• src/WebhookServer.Core/Execution/ProcessExecutor.cs — argv assembly per ExecutorType, stdin/env wiring, timeout
• src/WebhookServer.Core/Storage/DpapiSecret.cs — LocalMachine scope, base64 wire format
• src/WebhookServer.Core/Ipc/PipeSecurityFactory.cs — correct ACL or the GUI will fail silently for non-admins
• src/WebhookServer.Service/WebhookHost.cs — Kestrel setup with EnableBuffering() for body capture
• src/WebhookServer.Service/WebhookRouter.cs — auth → context → dispatch pipeline
• src/WebhookServer.Core/Callbacks/CallbackDispatcher.cs — bounded queue + retry/backoff; reuses HMAC code from Auth/HmacVerifier.cs for outbound signing
• src/WebhookServer.Gui/Views/EndpointEditor.xaml — the main UX surface; must make adding a "run this script when called" hook feel obvious

Verification (end-to-end)

Run on a Windows machine after dotnet publish -c Release:

1. Install service: sc.exe create WebhookServer binPath= "C:\path\to\WebhookServer.Service.exe" start= auto sc.exe start WebhookServer

2. Launch GUI (as Administrator). Confirm it connects to the pipe; the status indicator should show "running".

3. Smoke test (no auth, sync, PowerShell inline):

   • Endpoint slug /hook/ping, executor PowerShell, command 'pong'.
   • curl http://localhost:8080/hook/ping → body contains pong, exit code 0.

4. Bearer auth:

   • Set bearer secret s3cret.
   • curl http://localhost:8080/hook/ping → 401.
   • curl -H "Authorization: Bearer s3cret" http://localhost:8080/hook/ping → 200.

5. HMAC auth (GitHub-style):

   • Algo SHA256, header X-Hub-Signature-256, prefix sha256=, secret topsecret.
   • BODY='{"x":1}'; SIG=$(printf %s "$BODY" | openssl dgst -sha256 -hmac topsecret -hex | awk '{print $2}')
   • curl -H "X-Hub-Signature-256: sha256=$SIG" -d "$BODY" http://localhost:8080/hook/foo → 200.
   • Wrong sig → 401.

6. Stdin JSON + arg template:

   • PowerShell script: $j = $input | ConvertFrom-Json; "got repo=$($args[0]) name=$($j.name)"
   • Arg template: {{body.repo}}. POST {"repo":"acme","name":"bob"} → output contains got repo=acme name=bob.

7. Env-var passing:

   • cmd one-liner: echo event=%WEBHOOK_HEADER_X_GITHUB_EVENT%
   • curl -H "X-GitHub-Event: push" ... → output contains event=push.

8. Async endpoint:

   • PowerShell: Start-Sleep 10; "done". Mode = Async.
   • curl ... returns 202 immediately. GUI log shows done ~10s later.

9. Concurrency:

   • Endpoint with serialize=true and a Start-Sleep 5 script. Fire 3 parallel curls → durations ~5s, ~10s, ~15s. 9a. IP allowlist:
   • Set AllowedClients = ["127.0.0.1"]. curl http://localhost:8080/hook/ping → 200; from another machine on LAN → 403.
   • Set AllowedClients = ["10.10.1.0/24"]. Request from 10.10.1.42 → 200; from 10.10.2.5 → 403.
   • Empty list → all IPs allowed (regression check).
   • With TrustedProxies empty, send X-Forwarded-For: 127.0.0.1 from a non-allowed IP → still 403 (header not trusted).
   • With TrustedProxies = ["10.10.1.5"] and request coming from that IP carrying X-Forwarded-For: 192.168.50.20, allowlist ["192.168.50.20"] → 200. 9b. Outbound callback (async + HMAC-signed):
   • Stand up a tiny receiver: python -m http.server 9000 won't verify HMAC, so use a one-off script that prints the body and signature. Or another endpoint on this same server.
   • Configure an async endpoint with callback: Url = http://localhost:9000/sink, AuthMode = Hmac, secret cbsecret.
   • Trigger the webhook. After the script finishes, the receiver should see a POST with body { runId, exitCode, stdout, ... } and X-Hub-Signature-256: sha256=<hmac>.
   • Verify HMAC matches by recomputing with the secret — this proves outbound HMAC reuses the inbound code path correctly.
   • Stop the receiver, fire another async run → callback should retry with exponential backoff and eventually log gave-up after MaxAttempts.
   • Bring receiver back up before MaxAttempts exhausts → next retry delivers successfully.

10. HTTPS:

    • In GUI, bind a self-signed .pfx (New-SelfSignedCertificate ... -CertStoreLocation Cert:\LocalMachine\My).
    • curl -k https://localhost:8443/hook/ping → 200.

11. Reboot test:

    • Reboot. Verify service auto-starts and an existing endpoint still answers without launching the GUI.

12. Permissions test:

    • Run GUI as a non-admin user → should fail to connect to the named pipe with a clear error (not a hang).

Out of scope for v1 (call out in README)

• Importing/exporting config across machines (DPAPI-LocalMachine prevents this).
• Outbound webhook delivery / retry queues.
• Per-endpoint rate limiting.
• Multi-user RBAC for the GUI.
• Auto-update.