Files

T

justin b6e642da04 Docs: replace AD-reset recipe with realistic Zerto failover walkthrough

The AD password reset endpoint was a poor fit for what people actually
need this server for. Replaced with a realistic Zerto post-failover
example that's much closer to the project's purpose:

- Update DNS A records for failed-over hostnames
- Wait for the VM to come up at the DR site
- PowerShell-remote into the VM and check / start critical services
- Notify Teams with the result

The flagship pattern is now: Zerto post-script (curl, fire-and-forget)
calls an Async webhook endpoint -> 202 in milliseconds -> Zerto's
failover sequence is never blocked. The server runs the actual work in
the background, with full output captured in the daily log.

A ready-to-use Zerto-side script ships at
scripts/examples/zerto-post-failover.ps1 - pure curl.exe (no
PowerShell modules), reads the bearer token from a file the ZVM
service account can read.

The installer now bundles scripts/examples/ alongside docs/ so the
example is also available locally at
C:\Program Files\WebhookServer\scripts\examples\.

Removed: docs/recipes/ad-password-reset.md.
Updated: docs/README.md, README.md, the recipe content itself.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-05-08 10:47:44 -04:00

5.0 KiB

Raw Blame History

Webhook Server

A Windows-native webhook server that runs PowerShell, cmd / .bat, or any executable in response to incoming HTTP requests. Endpoints are configured in a desktop GUI; the actual server runs as a Windows Service so it survives reboots and works without anyone logged in.

Designed for sysadmins who want to wire up tools like Zerto pre/post scripts, GitHub webhooks, monitoring alerts, or backup jobs to Windows-side automation — without writing a custom listener every time.

Quickstart

Download the latest installer: https://github.com/recklessop/webhook-server/releases/latest
Run it. UAC accept → next, next, finish. Adds a Start Menu entry, registers and starts the Windows Service.
Open Webhook Server from the Start Menu (auto-elevates).
File → New endpoint, configure a slug + script, save, hit the URL.

Full first-time walkthrough: docs/installation.md

Highlights

Many endpoints, one service. Each webhook is a configured URL slug mapped to a script or command.
Per-endpoint auth — HMAC signature (GitHub / Stripe / Slack style), bearer token, or none.
Per-endpoint IP allowlist. Restrict by IP or CIDR. Empty list = open. Checked before auth so blocked IPs get a fast 403.
Per-endpoint Run As — run the hook as the service account (default), the user logged in at the keyboard (for UI hooks), or a named domain/local user via password.
Flexible execution. Windows PowerShell 5.1, PowerShell 7+, cmd / .bat, or any .exe.
Flexible input — any combination of: JSON body to stdin, query / headers as env vars, {{body.foo.bar}} template expansion into argv.
Sync or async per endpoint. Sync returns exit code + stdout / stderr to the caller; async returns 202 immediately.
Outbound callbacks. Optional per-endpoint URL the service POSTs run results to after the script finishes. HMAC-signed, retry-with-backoff. Required for async callers who want to know what happened.
Configurable network — bind to specific NICs, set the URL host shown in the GUI, configure trusted reverse proxies.
HTTPS optional. Bind a .pfx or cert-store thumbprint from the GUI.
Secrets at rest — bearer tokens, HMAC keys, RunAs passwords, and PFX passwords are DPAPI-encrypted (LocalMachine scope) in config.json.
Auto-snapshots. Every config save writes a Config Checkpoint; restore to any point with one click. Last 30 retained.

Architecture

+------------------+   named pipe    +-------------------------------+
|   GUI (WPF)      | <-------------> |  Windows Service              |
|  add / edit /    |  SYSTEM+admin   |  - Kestrel: hook listener     |
|  view logs       |  ACL'd          |  - Admin pipe server          |
+------------------+                 |  - Executor (process runner)  |
                                     |  - Callback dispatcher        |
                                     |  - Serilog file logging       |
                                     +-------------------------------+
                                                 |
                                     C:\ProgramData\WebhookServer\
                                       - config.json   (DPAPI-encrypted)
                                       - backups\      (auto-snapshots)
                                       - logs\         (daily rolling)

Documentation

Everything you need to operate the server:

Concepts — what a webhook is and how this server uses one
Installation — interactive and silent install
Upgrading — single click; what's preserved
Uninstalling — clean removal
Run As modes — Service / InteractiveUser / SpecificUser
Service account & Active Directory — gMSA + delegated rights
Network & security — bind addresses, allowlists, HTTPS, secrets
Troubleshooting — common errors and where to look

Recipes:

Zerto failover post-script → DNS + service checks ← canonical use case
GitHub-style HMAC-signed webhook
Pop UI on the user's desktop

A ready-to-drop-in Zerto-side script is included at scripts/examples/zerto-post-failover.ps1.

Requirements

Windows 10 / 11 / Server 2019+
x64
.NET 8 SDK to build (the released installer includes everything else)

Building from source

git clone https://github.com/recklessop/webhook-server.git
cd webhook-server

# Dev install (publishes + copies to C:\Program Files\WebhookServer + registers service)
powershell -ExecutionPolicy Bypass -File scripts\deploy.ps1

# Or build the installer locally (requires Inno Setup 6: winget install JRSoftware.InnoSetup)
powershell -ExecutionPolicy Bypass -File scripts\build-installer.ps1

License

TBD.

5.0 KiB Raw Blame History