Compare commits
3 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 justin
|
16ce906044 | ||
|
justin
|
a24d49f463 | ||
|
justin
|
e7e533d8c6 |
@@ -1,100 +0,0 @@
|
||||
name: Release (Gitea)
|
||||
|
||||
# Lives in .gitea/workflows/ so it runs on Gitea Actions only. The GitHub-side
|
||||
# release lives in .github/workflows/release.yml.
|
||||
#
|
||||
# Triggered automatically on v* tag pushes; can also be invoked manually via
|
||||
# workflow_dispatch with a version override (useful for testing the runner
|
||||
# without bumping the project version).
|
||||
|
||||
on:
|
||||
push:
|
||||
tags:
|
||||
- 'v*'
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
version:
|
||||
description: 'Version to build (e.g. 0.1.4). Defaults to Directory.Build.props.'
|
||||
required: false
|
||||
|
||||
jobs:
|
||||
build-installer:
|
||||
runs-on: windows-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Setup .NET
|
||||
uses: actions/setup-dotnet@v4
|
||||
with:
|
||||
dotnet-version: '8.0.x'
|
||||
|
||||
- name: Resolve version
|
||||
id: ver
|
||||
shell: pwsh
|
||||
run: |
|
||||
if ('${{ github.event_name }}' -eq 'push') {
|
||||
$v = '${{ github.ref_name }}'.TrimStart('v')
|
||||
} elseif ('${{ inputs.version }}') {
|
||||
$v = '${{ inputs.version }}'
|
||||
} else {
|
||||
[xml]$p = Get-Content Directory.Build.props
|
||||
$v = $p.Project.PropertyGroup.Version
|
||||
}
|
||||
"version=$v" | Out-File $env:GITHUB_OUTPUT -Append
|
||||
Write-Host "Building version $v"
|
||||
|
||||
- name: Restore + test
|
||||
shell: pwsh
|
||||
run: |
|
||||
dotnet restore WebhookServer.sln
|
||||
dotnet test WebhookServer.sln -c Release
|
||||
|
||||
- name: Ensure Inno Setup is installed
|
||||
shell: pwsh
|
||||
run: |
|
||||
if (-not (Get-Command iscc -ErrorAction SilentlyContinue) -and `
|
||||
-not (Test-Path 'C:\Program Files (x86)\Inno Setup 6\ISCC.exe') -and `
|
||||
-not (Test-Path 'C:\Program Files\Inno Setup 6\ISCC.exe')) {
|
||||
choco install innosetup --no-progress -y
|
||||
}
|
||||
|
||||
- name: Build installer
|
||||
shell: pwsh
|
||||
run: ./scripts/build-installer.ps1 -VersionOverride ${{ steps.ver.outputs.version }}
|
||||
|
||||
# actions/upload-artifact@v4 is GitHub-only ("GHESNotSupportedError" on
|
||||
# Gitea). The release-creation step below attaches the .exe via Gitea's
|
||||
# API directly, which is the only place we actually need to surface it.
|
||||
|
||||
- name: Create Gitea release with installer attached
|
||||
if: startsWith(github.ref, 'refs/tags/v')
|
||||
shell: pwsh
|
||||
env:
|
||||
GITEA_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
run: |
|
||||
$version = '${{ steps.ver.outputs.version }}'
|
||||
$tag = '${{ github.ref_name }}'
|
||||
$repo = '${{ github.repository }}'
|
||||
$serverUrl = '${{ github.server_url }}'
|
||||
$apiBase = "$serverUrl/api/v1/repos/$repo"
|
||||
$headers = @{ Authorization = "token $env:GITEA_TOKEN" }
|
||||
|
||||
# 1. Create the release.
|
||||
$isPre = $version.StartsWith('0.')
|
||||
$createBody = @{
|
||||
tag_name = $tag
|
||||
name = "Webhook Server $version"
|
||||
body = "Automated build via Gitea Actions runner."
|
||||
draft = $false
|
||||
prerelease = $isPre
|
||||
} | ConvertTo-Json
|
||||
$rel = Invoke-RestMethod -Uri "$apiBase/releases" -Method Post `
|
||||
-Headers $headers -ContentType 'application/json' -Body $createBody
|
||||
Write-Host "Created release id=$($rel.id) tag=$tag"
|
||||
|
||||
# 2. Attach the installer.
|
||||
$file = Get-Item "dist/WebhookServer-Setup-$version.exe"
|
||||
$uploadUri = "$apiBase/releases/$($rel.id)/assets?name=$($file.Name)"
|
||||
Invoke-RestMethod -Uri $uploadUri -Method Post -Headers $headers `
|
||||
-ContentType 'application/octet-stream' -InFile $file.FullName | Out-Null
|
||||
Write-Host "Uploaded $($file.Name) ($([math]::Round($file.Length / 1MB, 2)) MB) to $tag"
|
||||
@@ -5,7 +5,6 @@ on:
|
||||
branches: [main]
|
||||
pull_request:
|
||||
branches: [main]
|
||||
workflow_dispatch:
|
||||
|
||||
jobs:
|
||||
build:
|
||||
|
||||
@@ -12,9 +12,6 @@ on:
|
||||
|
||||
jobs:
|
||||
build-installer:
|
||||
# Gitea reads .github/workflows/ for compatibility, but the create-release
|
||||
# step uses a GitHub-only action. Skip the whole job on non-GitHub runners.
|
||||
if: github.server_url == 'https://github.com'
|
||||
runs-on: windows-latest
|
||||
permissions:
|
||||
contents: write # needed to create releases / upload assets
|
||||
|
||||
@@ -1,31 +0,0 @@
|
||||
name: Sync Wiki
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
paths:
|
||||
- 'docs/**'
|
||||
- 'scripts/sync-wiki.ps1'
|
||||
- '.github/workflows/wiki-sync.yml'
|
||||
workflow_dispatch:
|
||||
|
||||
jobs:
|
||||
sync:
|
||||
# Gitea reads .github/workflows/ for compatibility, but this workflow
|
||||
# pushes to a GitHub-hosted wiki. Skip on non-GitHub runners; the Gitea
|
||||
# wiki is synced separately via scripts/sync-wiki.ps1.
|
||||
if: github.server_url == 'https://github.com'
|
||||
runs-on: windows-latest
|
||||
permissions:
|
||||
contents: write
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Sync docs/ to GitHub wiki
|
||||
shell: pwsh
|
||||
env:
|
||||
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
run: |
|
||||
$repo = '${{ github.repository }}'
|
||||
$wikiUrl = "https://x-access-token:$env:GH_TOKEN@github.com/$repo.wiki.git"
|
||||
./scripts/sync-wiki.ps1 -WikiUrl $wikiUrl
|
||||
@@ -1,7 +1,7 @@
|
||||
<Project>
|
||||
|
||||
<PropertyGroup>
|
||||
<Version>0.1.5</Version>
|
||||
<Version>0.1.1</Version>
|
||||
<Authors>Justin Paul</Authors>
|
||||
<Company>Justin Paul</Company>
|
||||
<Product>Webhook Server</Product>
|
||||
@@ -9,7 +9,6 @@
|
||||
<PackageProjectUrl>https://jpaul.me</PackageProjectUrl>
|
||||
<RepositoryUrl>https://github.com/recklessop/webhook-server</RepositoryUrl>
|
||||
<RepositoryType>git</RepositoryType>
|
||||
<PackageLicenseExpression>MIT</PackageLicenseExpression>
|
||||
</PropertyGroup>
|
||||
|
||||
</Project>
|
||||
|
||||
@@ -1,21 +0,0 @@
|
||||
MIT License
|
||||
|
||||
Copyright (c) 2025-2026 Justin Paul
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
@@ -1,91 +1,111 @@
|
||||
# Webhook Server
|
||||
# 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.
|
||||
A Windows-native webhook server that runs PowerShell, PowerShell Core, cmd / `.bat`, or arbitrary executables 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
|
||||
|
||||
1. **Download** the latest installer: <https://github.com/recklessop/webhook-server/releases/latest>
|
||||
2. **Run it.** UAC accept → next, next, finish. Adds a Start Menu entry, registers and starts the Windows Service. The installer also downloads + installs the **.NET 8 runtimes** (ASP.NET Core + Desktop) if they're missing — fresh Windows Server installs need this.
|
||||
3. **Open Webhook Server** from the Start Menu (auto-elevates).
|
||||
4. **File → New endpoint**, configure a slug + script, save, hit the URL.
|
||||
|
||||
Full first-time walkthrough: [docs/installation.md](docs/installation.md)
|
||||
**Status:** planning complete, implementation pending. See [PLAN.md](PLAN.md) for the full design.
|
||||
|
||||
## 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.
|
||||
- **Per-endpoint auth.** Pick HMAC signature (GitHub/Stripe-style), bearer token, or none.
|
||||
- **Per-endpoint IP allowlist.** Restrict by IP or CIDR (IPv4 + IPv6). Empty list = open. Checked before auth.
|
||||
- **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.
|
||||
- **Flexible input.** Any combination of: JSON body to stdin, query/headers as env vars, `{{template}}` arg expansion.
|
||||
- **Sync or async per endpoint.** Sync returns exit code + stdout/stderr; async returns 202 immediately.
|
||||
- **Outbound callbacks.** Optional per-endpoint callback URL — service POSTs the run result back after the script finishes. Required for async callers who want to know what happened. HMAC-signed, retried with backoff. Pre-configured only (no SSRF surface from caller-supplied URLs).
|
||||
- **Service-first.** Always-on Windows Service. The WPF GUI is a thin config/monitor client over a named pipe.
|
||||
- **HTTPS optional.** Bind a `.pfx` or cert-store thumbprint from the GUI; HTTP works out of the box.
|
||||
- **Secrets at rest.** Tokens and HMAC secrets are encrypted via DPAPI (LocalMachine scope) in `config.json`.
|
||||
|
||||
## 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)
|
||||
+------------------+ 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
|
||||
```
|
||||
|
||||
## Documentation
|
||||
## Project layout (planned)
|
||||
|
||||
Everything you need to operate the server:
|
||||
|
||||
- [Concepts](docs/concepts.md) — what a webhook is and how this server uses one
|
||||
- [Installation](docs/installation.md) — interactive and silent install
|
||||
- [Upgrading](docs/upgrading.md) — single click; what's preserved
|
||||
- [Uninstalling](docs/uninstalling.md) — clean removal
|
||||
- [Run As modes](docs/runas-modes.md) — Service / InteractiveUser / SpecificUser
|
||||
- [Service account & Active Directory](docs/service-account-and-ad.md) — gMSA + delegated rights
|
||||
- [Network & security](docs/network-and-security.md) — bind addresses, allowlists, HTTPS, secrets
|
||||
- [Troubleshooting](docs/troubleshooting.md) — common errors and where to look
|
||||
|
||||
Recipes:
|
||||
|
||||
- [Zerto ZVMA (Kubernetes) pre/post → notify + VM health check](docs/recipes/zerto-zvma-pre-post.md) ← **canonical use case**
|
||||
- [GitHub-style HMAC-signed webhook](docs/recipes/github-style-hmac.md)
|
||||
- [Pop UI on the user's desktop](docs/recipes/ui-on-desktop.md)
|
||||
|
||||
The Zerto ZVMA recipe ships ready-to-drop-in scripts: [`scripts/examples/zerto-zvma-send.ps1`](scripts/examples/zerto-zvma-send.ps1) (sender, runs inside the ZVMA `scripts-service` container) plus [`zerto-receiver-notify.ps1`](scripts/examples/zerto-receiver-notify.ps1) and [`zerto-receiver-vm-healthcheck.ps1`](scripts/examples/zerto-receiver-vm-healthcheck.ps1) (receivers, run on the Webhook Server host).
|
||||
```
|
||||
WebhookServer.sln
|
||||
src/
|
||||
WebhookServer.Core/ class lib: models, auth, execution, storage, IPC
|
||||
WebhookServer.Service/ .NET 8 Worker Service (hosts Kestrel + admin pipe)
|
||||
WebhookServer.Gui/ WPF (.NET 8) MVVM config/monitor client
|
||||
scripts/
|
||||
install-service.ps1
|
||||
uninstall-service.ps1
|
||||
```
|
||||
|
||||
## Requirements
|
||||
|
||||
- Windows 10 / 11 / Server 2019+
|
||||
- x64
|
||||
- .NET 8 SDK to build (the released installer includes everything else)
|
||||
- Windows 10 / 11 or Windows Server 2019+
|
||||
- .NET 8 SDK to build, .NET 8 Runtime (or self-contained publish) to run
|
||||
- Administrator rights to install the service and to run the GUI (the admin named pipe is ACL'd to SYSTEM + Administrators)
|
||||
|
||||
## Building from source
|
||||
## Building (on Windows)
|
||||
|
||||
```powershell
|
||||
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
|
||||
dotnet restore
|
||||
dotnet build -c Release
|
||||
dotnet publish src/WebhookServer.Service -c Release -r win-x64 --self-contained
|
||||
dotnet publish src/WebhookServer.Gui -c Release -r win-x64 --self-contained
|
||||
```
|
||||
|
||||
## Installing the service (on Windows)
|
||||
|
||||
```powershell
|
||||
# from an elevated PowerShell prompt
|
||||
sc.exe create WebhookServer binPath= "C:\Program Files\WebhookServer\WebhookServer.Service.exe" start= auto
|
||||
sc.exe start WebhookServer
|
||||
```
|
||||
|
||||
`scripts/install-service.ps1` will wrap this once implemented and will accept a `-ServiceAccount` parameter.
|
||||
|
||||
## Service account & Active Directory
|
||||
|
||||
The service runs as `LocalSystem` by default — fine for local-only scripts and read-only AD queries (it authenticates to the domain as the computer account). If your webhook scripts need to **modify** AD (password resets, group changes, etc.), run the service under an account with the right delegated rights:
|
||||
|
||||
- **Recommended: gMSA** — Active Directory generates and rotates the password automatically.
|
||||
```powershell
|
||||
# on a DC, once
|
||||
New-ADServiceAccount -Name svc-webhookserver -DNSHostName host.domain.local `
|
||||
-PrincipalsAllowedToRetrieveManagedPassword "DOMAIN\WebhookHosts"
|
||||
# on the webhook host
|
||||
Install-ADServiceAccount svc-webhookserver
|
||||
sc.exe create WebhookServer binPath= "..." obj= "DOMAIN\svc-webhookserver$" start= auto
|
||||
```
|
||||
Note the trailing `$` and the absence of `password=`.
|
||||
|
||||
- **Plain domain user** — works on older domains, but you own password rotation:
|
||||
```powershell
|
||||
sc.exe create WebhookServer binPath= "..." obj= "DOMAIN\svc-webhookserver" password= "..." start= auto
|
||||
```
|
||||
|
||||
Don't use `LocalService` — it has no network identity and cannot talk to a domain controller.
|
||||
|
||||
> Heads up: any account the service runs under is the account your hook scripts run under. `LocalSystem` is the most powerful local account on the machine — treat webhook script contents as privileged.
|
||||
|
||||
## Configuration
|
||||
|
||||
The service reads `C:\ProgramData\WebhookServer\config.json`. Edit it through the GUI rather than by hand — the GUI handles DPAPI encryption of secrets and validation of IP allowlist entries.
|
||||
|
||||
## Out of scope for v1
|
||||
|
||||
- Importing/exporting config across machines (DPAPI LocalMachine scope ties decryption to the host).
|
||||
- Per-endpoint rate limiting.
|
||||
- Multi-user RBAC for the GUI.
|
||||
- Auto-update.
|
||||
|
||||
## License
|
||||
|
||||
[MIT](LICENSE). Use it for whatever you want, including commercial — just keep the copyright + license notice in copies and don't sue me when it eats your filesystem. No warranty, express or implied.
|
||||
Not yet chosen.
|
||||
|
||||
@@ -1,32 +0,0 @@
|
||||
# Webhook Server documentation
|
||||
|
||||
Webhook Server is a Windows service that runs a script (PowerShell, cmd, or any executable) when an HTTP request hits a URL you choose. It's designed for sysadmins who want to wire a tool like **Zerto pre/post scripts**, GitHub Actions, a monitoring system, or a backup tool into a Windows-side automation step — without writing a custom listener every time.
|
||||
|
||||
## New here? Start with these
|
||||
|
||||
1. [Concepts](concepts.md) — five-minute read on what a webhook is and how this server uses one
|
||||
2. [Installation](installation.md) — download, install, first endpoint
|
||||
3. [Recipe: Zerto ZVMA pre/post → notify + VM health check](recipes/zerto-zvma-pre-post.md) — the canonical reason this exists
|
||||
|
||||
## Topical
|
||||
|
||||
- [Upgrading](upgrading.md)
|
||||
- [Uninstalling](uninstalling.md)
|
||||
- [Run As modes — when to use which](runas-modes.md)
|
||||
- [Service account & Active Directory](service-account-and-ad.md)
|
||||
- [Network & security](network-and-security.md)
|
||||
- [Troubleshooting](troubleshooting.md)
|
||||
|
||||
## Recipes (cookbook style)
|
||||
|
||||
- [Zerto ZVMA (Kubernetes) pre/post → notify + VM health check](recipes/zerto-zvma-pre-post.md) ← canonical use case
|
||||
- [GitHub-style HMAC-signed webhook](recipes/github-style-hmac.md)
|
||||
- [Pop UI on the user's desktop](recipes/ui-on-desktop.md)
|
||||
|
||||
The Zerto ZVMA recipe ships with [`zerto-zvma-send.ps1`](../scripts/examples/zerto-zvma-send.ps1) (sender, runs inside the ZVMA `scripts-service` container) plus [`zerto-receiver-notify.ps1`](../scripts/examples/zerto-receiver-notify.ps1) and [`zerto-receiver-vm-healthcheck.ps1`](../scripts/examples/zerto-receiver-vm-healthcheck.ps1) (receivers, run on the Webhook Server host).
|
||||
|
||||
## Reference
|
||||
|
||||
- [GitHub repo](https://github.com/recklessop/webhook-server)
|
||||
- [Latest release](https://github.com/recklessop/webhook-server/releases/latest)
|
||||
- [Issue tracker](https://github.com/recklessop/webhook-server/issues)
|
||||
@@ -1,77 +0,0 @@
|
||||
# Concepts
|
||||
|
||||
If you've never used a webhook before, this is where to start. Five minutes, no surprises.
|
||||
|
||||
## What is a webhook?
|
||||
|
||||
A webhook is just **an HTTP URL that runs something when it gets called.** Some other tool — Zerto, GitHub, your monitoring system, a backup job — does an `HTTP POST` to that URL when an event happens. Whatever's listening on the URL takes that request and does work in response.
|
||||
|
||||
Concretely, a Zerto pre-script might do:
|
||||
|
||||
```powershell
|
||||
Invoke-WebRequest -Method POST -Uri http://webhooks.contoso.local:8080/hook/start-failover `
|
||||
-Body (@{ vmName = $env:ZertoVPGName } | ConvertTo-Json) `
|
||||
-ContentType application/json
|
||||
```
|
||||
|
||||
…and the server at `webhooks.contoso.local:8080` would receive that POST and run a PowerShell script you wrote.
|
||||
|
||||
## What does this server give you that you don't already have?
|
||||
|
||||
You could write a tiny ASP.NET listener, or run a PowerShell script behind IIS, or hand-craft `HttpListener` plumbing. People do, all the time. The trade-off is that **you then own the listener** — auth, retries, logging, restarts, a service wrapper, secret storage, an admin UI. That's where Webhook Server saves you a weekend.
|
||||
|
||||
What you get out of the box:
|
||||
|
||||
- A real **Windows Service** that survives reboots and runs without anyone logged in
|
||||
- Per-endpoint **authentication**: Bearer token, HMAC-signed (GitHub / Stripe / Slack style), or none
|
||||
- Per-endpoint **IP allowlist** (single IPs or CIDR ranges)
|
||||
- **Run-as identity**: the service runs as `LocalSystem` by default, but each individual hook can run as a domain account, the logged-in user, or whoever — without needing Task Scheduler in the middle
|
||||
- **Logging** (Serilog, daily-rolling files) plus a GUI tail
|
||||
- A WPF **GUI** for adding / editing / testing endpoints. No JSON file editing required.
|
||||
- **Outbound callbacks**: when a hook finishes, the server can POST the result to another URL, signed with HMAC, with retry-and-backoff
|
||||
- **HTTPS** via `.pfx` or a cert thumbprint from the local cert store
|
||||
- **Auto-snapshots** of your config on every save, with point-in-time restore from the GUI
|
||||
|
||||
## How the moving parts fit together
|
||||
|
||||
```
|
||||
+------------------+ 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 secrets)
|
||||
- backups\ (auto-snapshots)
|
||||
- logs\ (daily rolling)
|
||||
```
|
||||
|
||||
- The **Windows Service** does the actual work: listens for HTTP requests, runs your scripts, writes logs.
|
||||
- The **GUI** is purely a config + monitoring tool. It talks to the service over a named pipe ACL'd to `SYSTEM` and `Administrators`. You can launch and close the GUI as you like; the service keeps running.
|
||||
- **Config + secrets** live in `C:\ProgramData\WebhookServer\config.json`. Secrets (bearer tokens, HMAC keys, run-as passwords, PFX passwords) are DPAPI-encrypted with the `LocalMachine` scope, so the same machine can decrypt them under any account but they don't travel to other machines.
|
||||
|
||||
## What's an "endpoint"?
|
||||
|
||||
An endpoint is one URL slug (the part after `/hook/`) plus a configuration: who's allowed to call it, how it's authenticated, what to run when it fires, and what to do with the result. Add as many as you want.
|
||||
|
||||
| Field | What it controls |
|
||||
|---|---|
|
||||
| **Slug** | The URL path. `deploy` → `http://host:8080/hook/deploy` |
|
||||
| **Auth** | None / Bearer / HMAC. None means anyone who can reach the URL can fire it. |
|
||||
| **Allowed clients** | List of IPs or CIDRs allowed to hit this slug. Empty = anyone reachable. |
|
||||
| **Executor** | What to run: Windows PowerShell 5.1, PowerShell Core (7+), `cmd` / `.bat`, or a path to any `.exe` |
|
||||
| **Run As** | Who the script runs as. See [Run As modes](runas-modes.md). |
|
||||
| **Data passing** | How request data reaches the script — JSON to stdin, headers / query as env vars, `{{template}}` arg expansion |
|
||||
| **Response mode** | Sync (the HTTP caller waits for the script to finish and gets its output) or Async (returns 202 immediately, runs in background) |
|
||||
| **Callback** | Optional outbound URL the server POSTs to with the run result. Required for async hooks if the original caller wants the result. |
|
||||
|
||||
## What it isn't
|
||||
|
||||
- **Not an HTTP server for serving static files or pages.** Just hook URLs and a `/healthz`.
|
||||
- **Not a queue.** No durable persistence of inbound requests; if the service crashes mid-execution that run is lost (the inbound caller will see the connection drop or a timeout).
|
||||
- **Not multi-tenant.** It's one config, one set of endpoints, one machine. Run multiple instances on different ports / different machines if you need separation.
|
||||
- **Not an internet-facing public-API server out of the box.** Lock down with HTTPS + auth + IP allowlist + a reverse proxy if you're going to expose it publicly. See [network & security](network-and-security.md).
|
||||
@@ -1,132 +0,0 @@
|
||||
# Installation
|
||||
|
||||
This page covers a fresh install. If you already have Webhook Server installed, see [Upgrading](upgrading.md). To remove it, see [Uninstalling](uninstalling.md).
|
||||
|
||||
## Requirements
|
||||
|
||||
- Windows 10, Windows 11, or Windows Server 2019 / 2022 / 2025
|
||||
- Administrator rights to install the service and to run the GUI
|
||||
- **.NET 8 runtimes** (the installer downloads + installs them automatically if missing — see below)
|
||||
- (Optional, only if you publish from source) .NET 8 SDK
|
||||
|
||||
The installer is **x64 only**. There is no x86 build.
|
||||
|
||||
### .NET 8 runtimes
|
||||
|
||||
Webhook Server is published as framework-dependent (so the installer stays small) and needs two .NET 8 runtimes on the target machine:
|
||||
|
||||
| Runtime | Used by | Auto-installed by setup |
|
||||
|---|---|---|
|
||||
| ASP.NET Core 8 Runtime (`Microsoft.AspNetCore.App` 8.x) | the Service / Kestrel | Yes |
|
||||
| .NET Desktop Runtime 8 (`Microsoft.WindowsDesktop.App` 8.x) | the WPF GUI | Yes |
|
||||
|
||||
A clean Windows Server install has neither. The installer detects what's missing and downloads + installs each one silently before copying our files. If the machine has no internet access, install them manually first:
|
||||
|
||||
- ASP.NET Core 8 Runtime — <https://aka.ms/dotnet/8.0/aspnetcore-runtime-win-x64.exe>
|
||||
- .NET Desktop Runtime 8 — <https://aka.ms/dotnet/8.0/windowsdesktop-runtime-win-x64.exe>
|
||||
|
||||
Run each with `/install /quiet /norestart` for unattended installs, or just double-click. A reboot is rarely required.
|
||||
|
||||
To check what's already installed:
|
||||
|
||||
```powershell
|
||||
dotnet --list-runtimes
|
||||
# expect to see Microsoft.AspNetCore.App 8.x.y and Microsoft.WindowsDesktop.App 8.x.y
|
||||
```
|
||||
|
||||
## 1. Download
|
||||
|
||||
Grab the latest installer from the GitHub Releases page:
|
||||
|
||||
> https://github.com/recklessop/webhook-server/releases/latest
|
||||
|
||||
Look for the asset named `WebhookServer-Setup-X.Y.Z.exe`.
|
||||
|
||||
## 2. Run the installer
|
||||
|
||||
Double-click the `.exe`. UAC will prompt — accept. The wizard:
|
||||
|
||||
- Copies the binaries to `C:\Program Files\WebhookServer\`
|
||||
- Creates a Start Menu folder named **Webhook Server** with a GUI shortcut + Uninstall shortcut
|
||||
- Optionally creates a desktop shortcut (checkbox; off by default)
|
||||
- **Registers the Windows Service** named `WebhookServer`, runs it as `LocalSystem`, sets it to start automatically at boot, and configures it to restart on failure
|
||||
- Starts the service
|
||||
- Offers to launch the GUI when finished — leave the checkbox ticked
|
||||
|
||||
The first time the GUI opens, you'll see UAC prompt again because the GUI requires elevation (it talks to the service over a named pipe restricted to `SYSTEM` and the `Administrators` group). Accept it.
|
||||
|
||||
If the GUI's status bar shows a green dot and `Connected — HTTP 8080`, you're done.
|
||||
|
||||
> **Default ports**: HTTP on `8080`, HTTPS off. Both can be changed under **Server → Settings**. Port `8080` is rarely in use on a fresh server but conflicts with some other tools — if you see `Connection refused` later, this is the first thing to check.
|
||||
|
||||
## 3. Add your first endpoint
|
||||
|
||||
In the GUI:
|
||||
|
||||
1. **File → New endpoint**
|
||||
2. Slug: `ping`
|
||||
3. Auth → Mode: **None**
|
||||
4. Executor → Type: **Windows PowerShell**
|
||||
5. Executor → Inline command: `Write-Output 'pong'`
|
||||
6. Click **Save**
|
||||
|
||||
The endpoint appears in the grid. Right-click it → **Copy URL**, paste into a browser. You should get back something like:
|
||||
|
||||
```json
|
||||
{ "runId": "...", "exitCode": 0, "durationMs": 134, "stdout": "pong\r\n", ... }
|
||||
```
|
||||
|
||||
That's it. Real-world recipes start with [Zerto ZVMA pre/post → notify + VM health check](recipes/zerto-zvma-pre-post.md).
|
||||
|
||||
## Silent / unattended install
|
||||
|
||||
For deploying to many machines via Group Policy, SCCM, Intune, Ansible, etc. — the installer is built with [Inno Setup](https://jrsoftware.org/isinfo.php) and supports its standard silent-mode flags:
|
||||
|
||||
```powershell
|
||||
WebhookServer-Setup-0.1.1.exe /VERYSILENT /SUPPRESSMSGBOXES /NORESTART
|
||||
```
|
||||
|
||||
Useful flags:
|
||||
|
||||
| Flag | What it does |
|
||||
|---|---|
|
||||
| `/SILENT` | Show progress, no questions |
|
||||
| `/VERYSILENT` | No UI at all |
|
||||
| `/SUPPRESSMSGBOXES` | Suppress info / error popups (use with `/SILENT` or `/VERYSILENT`) |
|
||||
| `/NORESTART` | Don't restart automatically — there's nothing here that needs it, but pair with `/SUPPRESSMSGBOXES` for total quiet |
|
||||
| `/DIR="C:\Tools\WebhookServer"` | Override the install location |
|
||||
| `/LOG="C:\Temp\install.log"` | Write a verbose installer log |
|
||||
| `/TASKS="desktopicon"` | Pre-tick the optional desktop-icon task |
|
||||
|
||||
The post-install service install runs the same `install-service.ps1` script regardless of silent flags.
|
||||
|
||||
## Manual install from source (if you don't want to trust the prebuilt installer)
|
||||
|
||||
```powershell
|
||||
# clone (or your fork)
|
||||
git clone https://github.com/recklessop/webhook-server.git
|
||||
cd webhook-server
|
||||
|
||||
# from an elevated PowerShell:
|
||||
powershell -ExecutionPolicy Bypass -File scripts\deploy.ps1
|
||||
```
|
||||
|
||||
`deploy.ps1` publishes both projects, copies the binaries to `C:\Program Files\WebhookServer\`, registers the service, and starts it. Re-run after a `git pull` to upgrade.
|
||||
|
||||
To run the service under a non-default account (e.g. a gMSA for AD operations), pass `-ServiceAccount`:
|
||||
|
||||
```powershell
|
||||
.\scripts\deploy.ps1 -ServiceAccount 'CONTOSO\svc-webhookserver$'
|
||||
```
|
||||
|
||||
See [Service account & Active Directory](service-account-and-ad.md) for the full picture.
|
||||
|
||||
## Where things live after install
|
||||
|
||||
| Path | What |
|
||||
|---|---|
|
||||
| `C:\Program Files\WebhookServer\` | Binaries (`WebhookServer.Service.exe`, `WebhookServer.Gui.exe`, the icon, install/uninstall scripts) |
|
||||
| `C:\ProgramData\WebhookServer\config.json` | The configuration. Backups in `backups\`, daily-rolling logs in `logs\`. **Don't edit by hand** — secrets are DPAPI-encrypted and the service won't pick up your changes without a reload. Use the GUI. |
|
||||
| `\\.\pipe\WebhookServerAdmin` | The named pipe the GUI uses to talk to the service. ACL'd to `SYSTEM` + `Administrators` only. |
|
||||
|
||||
The installer never touches `C:\ProgramData\WebhookServer\`. Uninstalling preserves your config and logs by default; see [Uninstalling](uninstalling.md) for how to wipe them too.
|
||||
@@ -1,131 +0,0 @@
|
||||
# Network & security
|
||||
|
||||
This page covers what's exposed by Webhook Server, how to lock it down, and what's safe to change vs. leave alone.
|
||||
|
||||
## What's listening
|
||||
|
||||
By default the service binds Kestrel to **all interfaces on TCP 8080**. There are two endpoints relevant to outsiders:
|
||||
|
||||
- `GET|POST /hook/<slug>` — fires a configured endpoint
|
||||
- `GET /healthz` — returns `{"ok": true}` for monitoring
|
||||
- `GET /favicon.ico` — returns 204 to keep browser logs clean
|
||||
|
||||
Plus the admin named pipe `\\.\pipe\WebhookServerAdmin`, which is **only available locally** to processes running as SYSTEM or in the Administrators group.
|
||||
|
||||
## Reducing the network exposure
|
||||
|
||||
### Bind only to specific NICs
|
||||
|
||||
By default the server listens on every IP the host has — useful on a single-NIC desktop, dangerous on a multi-NIC server where one NIC faces the internet.
|
||||
|
||||
In the GUI: **Server → Settings → Network**. Untick "Listen on all interfaces" and tick the specific addresses you want. Save. The service restarts automatically and rebinds.
|
||||
|
||||
Common patterns:
|
||||
|
||||
- **Internal-only**: tick the LAN IP(s), leave loopback ticked too if anything on the box itself calls the hook
|
||||
- **Loopback-only**: tick `127.0.0.1` and `::1`. Useful when a reverse proxy on the same host fronts the public traffic.
|
||||
- **One specific IP for hooks**: tick a single IP that you've documented as the webhook endpoint. Helps when you have a multi-homed server and want clear network segmentation.
|
||||
|
||||
### Per-endpoint IP allowlist
|
||||
|
||||
Each endpoint has an **IP allowlist** field. Empty means anyone reachable can call it. Non-empty means deny-by-default — only the listed IPs / CIDRs are allowed:
|
||||
|
||||
```
|
||||
192.168.1.0/24
|
||||
10.42.0.5
|
||||
fd00::/8
|
||||
```
|
||||
|
||||
Mixing IPv4 and IPv6 entries is fine. The check runs **before authentication**, so a blocked IP gets a fast 403 without burning CPU on HMAC validation.
|
||||
|
||||
### Trusted proxies (X-Forwarded-For)
|
||||
|
||||
If the server sits behind a reverse proxy (nginx / IIS / Caddy / Cloudflare Tunnel), the inbound `RemoteIpAddress` will always be the proxy. To make the IP allowlist evaluate the original client instead, configure **Server → Settings → Trusted proxies** with the IP(s) of the proxy:
|
||||
|
||||
```
|
||||
10.0.0.5
|
||||
```
|
||||
|
||||
When the inbound connection comes from that IP and includes an `X-Forwarded-For` header, the leftmost entry of the header is treated as the effective client IP for the allowlist check.
|
||||
|
||||
If `Trusted proxies` is empty (default), `X-Forwarded-For` is **ignored entirely**. This is the safe default — it prevents anyone from spoofing their IP by adding the header themselves.
|
||||
|
||||
## Authentication options
|
||||
|
||||
| Mode | When to use | What the caller sends |
|
||||
|---|---|---|
|
||||
| **None** | Internal-only on a trusted LAN, or a hook that's safe to fire repeatedly with no side effects | Nothing |
|
||||
| **Bearer** | Simple authentication. Pick a long random secret and treat it as a password. | `Authorization: Bearer <secret>` |
|
||||
| **HMAC** | Anything where the body matters and you want tamper-evidence: GitHub webhooks, Stripe events, signed callbacks | A header (default `X-Hub-Signature-256`) containing `sha256=<hex digest>` of the request body keyed by your shared secret |
|
||||
|
||||
For **None**, lean hard on the IP allowlist — that's your only defense.
|
||||
|
||||
For **Bearer**, generate the secret with `[Convert]::ToBase64String((1..32 | %{ Get-Random -Maximum 256 }))` or any password manager. 32+ bytes of entropy. The token sits in `Authorization` headers; HTTPS is **strongly recommended** so it doesn't traverse the network in clear text.
|
||||
|
||||
For **HMAC**, the secret never traverses the network — only the digest does. This is what GitHub / Stripe / Slack use, and it's the right pick for inbound webhooks from internet-facing services. Configure the four fields to match the sender:
|
||||
|
||||
- **Algorithm**: usually SHA256
|
||||
- **Header name**: e.g. `X-Hub-Signature-256` (GitHub), `X-Slack-Signature` (Slack), `Stripe-Signature` (Stripe — needs different format)
|
||||
- **Prefix**: `sha256=` for GitHub-style, none for raw hex
|
||||
- **Encoding**: hex (most senders) or base64 (some Slack-derived implementations)
|
||||
|
||||
## HTTPS
|
||||
|
||||
HTTP-only is fine for fully-internal use. For anything reachable beyond a trusted LAN, enable HTTPS.
|
||||
|
||||
In **Server → Settings → HTTPS**:
|
||||
|
||||
- **PFX file**: path to a `.pfx` and its password. Easiest if you got a cert from your internal CA or generated a self-signed one with `New-SelfSignedCertificate`.
|
||||
- **Cert store thumbprint**: the SHA-1 thumbprint of a certificate already imported into `LocalMachine\My`. Best for production where IT manages the cert lifecycle (auto-renewal, revocation).
|
||||
|
||||
The **HTTPS port** defaults to 8443. Both HTTP and HTTPS can be active simultaneously — change `HTTP port` and `HTTPS port` independently.
|
||||
|
||||
After saving HTTPS settings the service restarts and rebinds. There is briefly a "Disconnected" state in the GUI while that happens (1–3 seconds).
|
||||
|
||||
### Using Let's Encrypt
|
||||
|
||||
The server doesn't speak ACME directly. Two practical options:
|
||||
|
||||
1. **Reverse proxy approach** — run nginx / Caddy / IIS in front of Webhook Server. The proxy handles Let's Encrypt; Webhook Server stays HTTP-only on loopback. Configure `Trusted proxies` so allowlists still work on the original client IP.
|
||||
2. **External cert renewal** — use [`win-acme`](https://www.win-acme.com/) to obtain certs and place them in `LocalMachine\My`. Configure HTTPS by **thumbprint** in the GUI. When `win-acme` rotates the cert it produces a new thumbprint, so you'll need to update the GUI; or have a small scheduled task that calls the admin pipe to update the binding (advanced, undocumented for now).
|
||||
|
||||
## Secrets at rest
|
||||
|
||||
All secrets — bearer tokens, HMAC keys, PFX passwords, RunAs passwords — are encrypted in `config.json` using **DPAPI with the `LocalMachine` scope**:
|
||||
|
||||
- The same machine can decrypt them under any account (so changing the service account doesn't break secret access).
|
||||
- Copying `config.json` to a different machine **doesn't carry the secrets** — DPAPI LocalMachine binds to the host's machine key. This is by design and protects against config exfiltration.
|
||||
- The GUI displays decrypted secrets in plaintext for an admin user. This is intentional. Anyone who can connect to the admin pipe is already SYSTEM-equivalent on the host; pretending otherwise just makes secret recovery harder.
|
||||
|
||||
For backup-and-restore across machines, you'd need to either:
|
||||
|
||||
- Re-enter all secrets on the new host (use the **Export config → manual secret re-entry** flow)
|
||||
- Bind a custom DPAPI scope (not currently supported — would require a v0.x feature request)
|
||||
|
||||
## The admin pipe
|
||||
|
||||
`\\.\pipe\WebhookServerAdmin` carries the GUI's commands to the service. Its security descriptor allows full control to:
|
||||
|
||||
- `NT AUTHORITY\SYSTEM`
|
||||
- `BUILTIN\Administrators`
|
||||
|
||||
Everyone else gets denied at the OS level — there's no auth layer in the protocol itself because the ACL is the auth layer. UAC token splitting means a non-elevated process owned by an Admin user is **also denied** (because the user's standard token has Admins as deny-only). That's why the GUI exe is manifested with `requireAdministrator` — it auto-elevates so the pipe accepts the connection.
|
||||
|
||||
If you ever need to grant pipe access to another local group (e.g., a custom `WebhookOperators` group), edit `src/WebhookServer.Core/Ipc/PipeSecurityFactory.cs` and add an `AddAccessRule` for that group. Currently no GUI configures this.
|
||||
|
||||
## Threat model summary
|
||||
|
||||
What you're protected against, by default:
|
||||
|
||||
- **Random scanners hitting your hooks** — solved by IP allowlists (when configured), auth (when configured), and HTTPS (when configured)
|
||||
- **Replay of inbound requests** — HMAC signs the body, so a captured request can't be modified, but it CAN be replayed. If that matters, include a timestamp in the body and reject old timestamps in your script.
|
||||
- **Credential leaks** — secrets at rest are DPAPI-encrypted, machine-bound; they don't travel with `config.json`
|
||||
- **Privilege escalation via the admin pipe** — pipe ACL excludes non-admins
|
||||
- **Local user spoofing the source IP** — `X-Forwarded-For` is ignored unless you explicitly trust a proxy
|
||||
|
||||
What you're NOT protected against — these are out of scope for this server:
|
||||
|
||||
- Compromise of an admin account on the host (game over — they own everything)
|
||||
- A malicious script you configured (you wrote it; the server just runs it)
|
||||
- DoS via volume of requests — there's no rate limiting in v0.x
|
||||
- Memory dump of the running service revealing decrypted secrets — DPAPI protects at-rest only
|
||||
@@ -1,122 +0,0 @@
|
||||
# Recipe: GitHub-style HMAC-signed webhook
|
||||
|
||||
GitHub, Stripe, Slack, Shopify, and most SaaS providers sign their outbound webhooks with HMAC. The receiver computes the same HMAC over the request body using a shared secret and rejects the request if the signatures don't match. Webhook Server has this built in — you just point a real GitHub webhook at your endpoint.
|
||||
|
||||
## What we're building
|
||||
|
||||
A webhook URL that GitHub calls on every push to a repo. The server runs a PowerShell script that pulls the latest commit and triggers a deployment. Authentication is HMAC-SHA256 over the request body, using the secret you configured in GitHub's webhook settings.
|
||||
|
||||
## On the GitHub side
|
||||
|
||||
In your repo: **Settings → Webhooks → Add webhook**.
|
||||
|
||||
| Field | Value |
|
||||
|---|---|
|
||||
| Payload URL | `https://hooks.contoso.com/hook/gh-deploy` (yes, HTTPS — GitHub enforces it for public hosts) |
|
||||
| Content type | `application/json` |
|
||||
| Secret | Generate a long random string. Copy it for the next step. |
|
||||
| SSL verification | Enable |
|
||||
| Events | Just `push` |
|
||||
|
||||
Save. GitHub immediately delivers a `ping` event for testing. You'll see it in **Recent Deliveries** with whatever response code your server returns.
|
||||
|
||||
## The PowerShell deployment script
|
||||
|
||||
`C:\Scripts\gh-deploy.ps1`:
|
||||
|
||||
```powershell
|
||||
[CmdletBinding()]
|
||||
param()
|
||||
|
||||
$ErrorActionPreference = 'Stop'
|
||||
|
||||
$payload = $input | ConvertFrom-Json
|
||||
|
||||
# Verify the event type via the X-GitHub-Event header passed as an env var
|
||||
$event = $env:WEBHOOK_HEADER_X_GITHUB_EVENT
|
||||
if ($event -eq 'ping') {
|
||||
"got ping from $($payload.repository.full_name)"
|
||||
return
|
||||
}
|
||||
if ($event -ne 'push') {
|
||||
Write-Error "ignoring $event event"
|
||||
}
|
||||
|
||||
$repo = $payload.repository.full_name
|
||||
$branch = $payload.ref -replace '^refs/heads/', ''
|
||||
$sha = $payload.after
|
||||
|
||||
if ($branch -ne 'main') {
|
||||
"ignoring push to $branch"
|
||||
return
|
||||
}
|
||||
|
||||
$repoDir = "C:\Deploys\$($payload.repository.name)"
|
||||
if (-not (Test-Path $repoDir)) {
|
||||
git clone "https://github.com/$repo.git" $repoDir
|
||||
}
|
||||
|
||||
Push-Location $repoDir
|
||||
try {
|
||||
git fetch --all
|
||||
git reset --hard $sha
|
||||
# ...your build/deploy steps here...
|
||||
& npm ci
|
||||
& npm run build
|
||||
Restart-Service MyAppService
|
||||
}
|
||||
finally {
|
||||
Pop-Location
|
||||
}
|
||||
|
||||
"deployed $repo @ $sha"
|
||||
```
|
||||
|
||||
## Configure the endpoint
|
||||
|
||||
**File → New endpoint**:
|
||||
|
||||
| Section | Setting | Value |
|
||||
|---|---|---|
|
||||
| Identity | Slug | `gh-deploy` |
|
||||
| Auth | Mode | **HMAC** |
|
||||
| Auth | HMAC secret | paste the GitHub-side secret |
|
||||
| Auth | HMAC header | `X-Hub-Signature-256` *(GitHub's default)* |
|
||||
| Allowed clients | | `140.82.112.0/20`, `192.30.252.0/22` *(GitHub's webhook IP ranges; check [docs.github.com](https://api.github.com/meta) for the live list)* |
|
||||
| Executor | Type | **Windows PowerShell** |
|
||||
| Executor | Script path | `C:\Scripts\gh-deploy.ps1` |
|
||||
| Data passing | JSON body to stdin | ✓ |
|
||||
| Data passing | Headers/query as env vars | ✓ *(needed so `WEBHOOK_HEADER_X_GITHUB_EVENT` is set)* |
|
||||
| Run as | Identity | **Service** (default) — assumes the deployment is local |
|
||||
| Response | Mode | **Async** *(GitHub times out fast; don't make it wait for the build)* |
|
||||
| Response | Timeout (sec) | `600` |
|
||||
|
||||
Save.
|
||||
|
||||
## What HMAC does for you here
|
||||
|
||||
GitHub computes `sha256(body, secret)` and sends it as `sha256=<hex>` in `X-Hub-Signature-256`. Webhook Server computes the same hash, verifies in fixed time, and rejects (401) on mismatch.
|
||||
|
||||
This means:
|
||||
|
||||
- A request with a tampered body fails the check
|
||||
- A captured request can be **replayed verbatim** (the signature is valid for that body) — if that matters, GitHub also includes a `X-GitHub-Delivery` ID and timestamp you can deduplicate against
|
||||
- The secret never travels over the network — only the digest does, so HTTPS is for confidentiality of the body, not the secret
|
||||
|
||||
## Adapting for Stripe, Slack, etc.
|
||||
|
||||
Same pattern, different headers and signing details. The four HMAC fields in the editor cover all common variants:
|
||||
|
||||
| Provider | Header | Prefix | Encoding | Algorithm |
|
||||
|---|---|---|---|---|
|
||||
| GitHub | `X-Hub-Signature-256` | `sha256=` | hex | SHA-256 |
|
||||
| Stripe | `Stripe-Signature` | (none — but Stripe's format is multipart, see below) | hex | SHA-256 |
|
||||
| Slack | `X-Slack-Signature` | `v0=` | hex | SHA-256 |
|
||||
| Generic / custom | configurable | configurable | configurable | SHA-1 / SHA-256 / SHA-512 |
|
||||
|
||||
**Stripe** is special: their `Stripe-Signature` header has the format `t=<timestamp>,v1=<sig>,v0=<sig>`, where `v1` is HMAC-SHA256 of `<timestamp>.<body>`. Webhook Server's straight HMAC check doesn't match Stripe's signed-with-timestamp scheme. Workarounds:
|
||||
|
||||
- Use **Bearer auth** on Stripe webhooks instead, since you already control the secret
|
||||
- Or do unauthenticated + IP allowlist + a script-side signature check using their official validation library
|
||||
|
||||
For everything that's "GitHub-shaped" (signed body, raw HMAC), the built-in HMAC mode is the right pick.
|
||||
@@ -1,68 +0,0 @@
|
||||
# Recipe: Pop UI on the user's desktop
|
||||
|
||||
The classic "fire a hook from your phone, see a calculator window appear on your PC." Useful for:
|
||||
|
||||
- Triggering interactive installers / wizards
|
||||
- Opening browser tabs to specific dashboards on demand
|
||||
- Playing a sound / showing a toast notification
|
||||
- Demos and party tricks
|
||||
|
||||
## Why this is non-trivial on Windows
|
||||
|
||||
The Webhook Server service runs as `LocalSystem` in **session 0**. Anything launched normally from a Service-mode endpoint also lands in session 0, which has no visible desktop — UI runs but nobody sees it. To put a window on the desktop of whoever is logged in at the keyboard, the service has to:
|
||||
|
||||
1. Find the active console session ID (`WTSGetActiveConsoleSessionId`)
|
||||
2. Get a primary token for the user in that session (`WTSQueryUserToken`)
|
||||
3. Spawn the new process with `CreateProcessAsUser` against that token, targeting `winsta0\default`
|
||||
|
||||
Webhook Server does all of this for you when the endpoint's **Run as** is set to **InteractiveUser**.
|
||||
|
||||
## Configure the endpoint
|
||||
|
||||
| Section | Setting | Value |
|
||||
|---|---|---|
|
||||
| Identity | Slug | `calc` |
|
||||
| Identity | Description | "Pop calculator on the logged-in user's desktop" |
|
||||
| Auth | Mode | None / Bearer — your call |
|
||||
| Allowed clients | | restrict; this is interactive UI |
|
||||
| Executor | Type | **Executable** |
|
||||
| Executor | Executable path | `C:\Windows\System32\calc.exe` |
|
||||
| Run as | Identity | **InteractiveUser** |
|
||||
| Response | Mode | **Async** *(calc never exits on its own; sync would 30-second-timeout-kill it every time)* |
|
||||
| Response | Fail on non-zero exit | unticked |
|
||||
|
||||
Save. Hit `http://localhost:8080/hook/calc` from anywhere — calc.exe pops up on your desktop.
|
||||
|
||||
## Limits
|
||||
|
||||
- **Service must run as LocalSystem.** Only SYSTEM has the `SeTcbPrivilege` required for `WTSQueryUserToken`. If you switched the service to a gMSA (e.g. for AD-write hooks), this mode stops working. Run two instances of Webhook Server on different ports if you need both.
|
||||
- **Someone must be logged in** at the console. If the desktop is at the lock screen with no user signed in, the hook fails with `No active console session - is anyone logged in at the keyboard?`.
|
||||
- **RDP sessions complicate things.** `WTSGetActiveConsoleSessionId` always returns the *console* session, not RDP sessions. If only RDP users are connected and no one is at the physical keyboard, this mode fails. (A separate API, `WTSQueryUserToken` against an enumerated session ID, can target RDP — that'd be a v0.x feature request.)
|
||||
- **Multiple users logged in via fast-user-switching** — the hook lands in whichever session is currently active (the foreground desktop), not all of them.
|
||||
|
||||
## Variations
|
||||
|
||||
### Notification toast instead of a window
|
||||
|
||||
Use a PowerShell script that emits a Windows 10/11 toast via `BurntToast` (third-party module) or the built-in WinRT API:
|
||||
|
||||
```powershell
|
||||
# requires: Install-Module BurntToast
|
||||
New-BurntToastNotification -Text 'Webhook fired',$($input | Out-String)
|
||||
```
|
||||
|
||||
Configure the endpoint as InteractiveUser + WindowsPowerShell + inline command. The toast appears as the logged-in user — same as if they fired it themselves.
|
||||
|
||||
### Open a URL in the user's default browser
|
||||
|
||||
```powershell
|
||||
Start-Process ($input | ConvertFrom-Json).url
|
||||
```
|
||||
|
||||
Body: `{ "url": "https://contoso.servicenow.com/incident/123" }`
|
||||
|
||||
This opens the URL in whatever the user has set as default. Handy for "page on-call → they reply on their phone with a link → URL opens on their workstation when they sit down."
|
||||
|
||||
### Run a setup wizard / installer that needs UI
|
||||
|
||||
Some installers refuse to run silently or have steps that require human input. Wrap them as InteractiveUser hooks so the operator can trigger them from a help-desk console without having to RDP in.
|
||||
@@ -1,275 +0,0 @@
|
||||
# Recipe: Zerto ZVMA pre/post scripts → notify + VM health check
|
||||
|
||||
> This is the **canonical** Zerto recipe. It targets the **ZVMA on
|
||||
> Kubernetes** — the supported deployment — where pre/post scripts run
|
||||
> inside the in-cluster `scripts-service` container (Linux + pwsh 7). The
|
||||
> webhook-server side is a normal Windows service that does the
|
||||
> Windows-domain work the ZVMA container can't reach directly.
|
||||
|
||||
## What we're building
|
||||
|
||||
ZVMA's `scripts-service` pod runs your VPG pre/post scripts inside a Linux
|
||||
container. It exposes a small set of `Zerto*` environment variables, and we
|
||||
want to:
|
||||
|
||||
1. POST those variables to a Webhook Server endpoint at the start (pre) and
|
||||
end (post) of every VPG operation, and
|
||||
2. On the receiving Windows host, do something useful with them — at minimum
|
||||
a chat notification, and on `post` a quick health check of the VMs that
|
||||
just powered on.
|
||||
|
||||
The endpoints are **Async**, so the Zerto VPG sequence is never blocked by
|
||||
slow downstream actions (notifications, port probes, etc.).
|
||||
|
||||
```
|
||||
Zerto VPG operation starts
|
||||
|
|
||||
+-- ZVMA scripts-service container runs:
|
||||
| /app/scripts-files/zerto-zvma-send.ps1 -Phase pre
|
||||
| -> POST http://webhook.dr/hook/zerto-pre (async, returns 202)
|
||||
|
|
||||
+-- VMs come up at recovery site
|
||||
|
|
||||
+-- ZVMA scripts-service container runs:
|
||||
/app/scripts-files/zerto-zvma-send.ps1 -Phase post
|
||||
-> POST http://webhook.dr/hook/zerto-post (async, returns 202)
|
||||
|
||||
(meanwhile, on the webhook server)
|
||||
/hook/zerto-pre -> Slack/Teams notification ("Test failover starting...")
|
||||
/hook/zerto-post -> Slack/Teams notification + ping/port probe each VM,
|
||||
write a JSON report to disk, exit non-zero on failure.
|
||||
```
|
||||
|
||||
## What ZVMA exposes
|
||||
|
||||
Captured from a real Test failover; same set is present in pre and post:
|
||||
|
||||
| Variable | Example | Notes |
|
||||
|---|---|---|
|
||||
| `ZertoVPGName` | `ubuntu-2404-local` | The VPG that fired the script |
|
||||
| `ZertoInternalVpgName` | `ubuntu-2404-local` | Usually identical to `ZertoVPGName` |
|
||||
| `ZertoOperation` | `Test` | `Test` / `Failover` / `Move` / `FailoverBeforeCommit` / `FailoverDuringCommit` |
|
||||
| `ZertoForce` | `Yes` (pre) / `No` (post) | Set to `Yes` only during the pre phase when force mode is on; reset to `No` by post |
|
||||
| `VmDisplayNames` | `ubuntu-2404(1)(1)(1)` | Comma-separated for multi-VM VPGs; Test failovers add `(N)` suffixes |
|
||||
| `ZertoHypervisorManagerIP` | `192.168.50.20` | The vCenter / Hyper-V manager ZVMA is talking to |
|
||||
| `ZertoHypervisorManagerPort` | `443` | |
|
||||
| `ZertoOutputDir` | `/app/scripts-output` | Container-side output dir (written back to ZVMA via PVC) |
|
||||
| `ZertoWorkingDir` | `/app/scripts-files` | Where script files live in-container |
|
||||
|
||||
Branch on `ZertoOperation` to differentiate Test runs from real failovers.
|
||||
**`ZertoForce` is only meaningful during the pre phase** — capture it there
|
||||
if you need it later, because by post it's been reset.
|
||||
|
||||
## 1. The Zerto-side script (sender)
|
||||
|
||||
A ready-to-use script ships in this repo at
|
||||
[`scripts/examples/zerto-zvma-send.ps1`](../../scripts/examples/zerto-zvma-send.ps1).
|
||||
Place it where the `scripts-service` pod can read it — typically the
|
||||
`scripts-service-scripts-files-pvc`, mounted at `/app/scripts-files/` — and
|
||||
wire it into the VPG twice:
|
||||
|
||||
> **VPG settings → Recovery → Scripts → Pre-Recovery Script**
|
||||
> Path: `/app/scripts-files/zerto-zvma-send.ps1`
|
||||
> Parameters: `-Phase pre`
|
||||
>
|
||||
> **VPG settings → Recovery → Scripts → Post-Recovery Script**
|
||||
> Path: `/app/scripts-files/zerto-zvma-send.ps1`
|
||||
> Parameters: `-Phase post`
|
||||
|
||||
The default `$WebhookUrl` includes `{phase}` so one script + one URL config
|
||||
serves both phases — `http://webhook.dr/hook/zerto-{phase}` becomes
|
||||
`/hook/zerto-pre` and `/hook/zerto-post` automatically. Override with
|
||||
`-WebhookUrl` and `-Bearer` if you'd rather pass them per-VPG.
|
||||
|
||||
The script POSTs a single JSON object:
|
||||
|
||||
```json
|
||||
{
|
||||
"phase": "pre",
|
||||
"capturedAt": "2026-05-08T17:45:54Z",
|
||||
"host": "scripts-service-f9b6cb7-4xbxq",
|
||||
"zerto": {
|
||||
"vpgName": "ubuntu-2404-local",
|
||||
"internalVpgName": "ubuntu-2404-local",
|
||||
"operation": "Test",
|
||||
"force": "Yes",
|
||||
"vmDisplayNames": "ubuntu-2404(1)(1)(1)",
|
||||
"hypervisorManagerIP": "192.168.50.20",
|
||||
"hypervisorManagerPort": "443",
|
||||
"outputDir": "/app/scripts-output",
|
||||
"workingDir": "/app/scripts-files"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
A webhook outage **does not fail the VPG** — the script catches and exits 0.
|
||||
Comment in the file shows how to flip that to strict mode if you'd rather a
|
||||
webhook outage abort the failover.
|
||||
|
||||
## 2. The webhook-server-side scripts (receivers)
|
||||
|
||||
Two examples ship in the repo. Both read the JSON body from stdin (the
|
||||
webhook server delivers the body to the script's stdin when **JSON body to
|
||||
stdin** is ticked on the endpoint).
|
||||
|
||||
### a. Slack/Teams notification — both phases
|
||||
|
||||
[`scripts/examples/zerto-receiver-notify.ps1`](../../scripts/examples/zerto-receiver-notify.ps1)
|
||||
posts a single-line summary to a Slack or Teams Incoming Webhook URL. It
|
||||
picks an icon based on `ZertoOperation`:
|
||||
|
||||
- `Test` → 🧪 — benign, expected
|
||||
- `Failover` → 🚨 — real production event
|
||||
- `Move` → 🚚 — planned migration
|
||||
|
||||
…and highlights `ZertoForce=Yes` on the **pre** message so you can see at
|
||||
a glance whether the operation was force-flagged.
|
||||
|
||||
Set the destination via `NOTIFY_URL` env var on the webhook host, or
|
||||
hardcode at the top of the script.
|
||||
|
||||
### b. Post-recovery VM health check — post phase only
|
||||
|
||||
[`scripts/examples/zerto-receiver-vm-healthcheck.ps1`](../../scripts/examples/zerto-receiver-vm-healthcheck.ps1)
|
||||
runs only on `phase=post` for operations that bring VMs up
|
||||
(`Test`/`Failover`/`Move`/`FailoverBeforeCommit`/`FailoverDuringCommit`).
|
||||
For each name in `VmDisplayNames` it:
|
||||
|
||||
1. Strips the trailing `(1)(1)(1)` suffix Zerto adds on Test failovers, so
|
||||
DNS resolution targets the actual hostname.
|
||||
2. Pings (`Test-Connection`).
|
||||
3. Probes a configurable TCP port (`-ProbePort`, default `3389` for RDP;
|
||||
use `22` for SSH or `443` for the web tier).
|
||||
4. Writes a JSON report to
|
||||
`C:\ProgramData\WebhookServer\zerto-healthchecks\<vpg>-<op>-<utcstamp>.json`.
|
||||
5. Exits non-zero if any VM failed either probe — which surfaces in the
|
||||
webhook server's run history (and outbound callback, if configured).
|
||||
|
||||
Bump the endpoint's **Timeout (sec)** to `120` when wiring this in, since
|
||||
network probes can take a while.
|
||||
|
||||
## 3. Configure the endpoints in the GUI
|
||||
|
||||
Two endpoints. Identical except for the slug, the script, and (for the
|
||||
healthcheck) the timeout.
|
||||
|
||||
### `zerto-pre`
|
||||
|
||||
| Section | Setting | Value |
|
||||
|---|---|---|
|
||||
| Identity | Slug | `zerto-pre` |
|
||||
| Identity | Description | "Zerto pre-recovery: chat notification" |
|
||||
| Auth | Mode | **Bearer** |
|
||||
| Auth | Bearer secret | generate a 32-byte random string; reuse for `zerto-post` |
|
||||
| Allowed clients | (one per line) | the IP of the K8s node running `scripts-service` (e.g. `192.168.50.30`) |
|
||||
| Executor | Type | **Windows PowerShell** (or PowerShell 7) |
|
||||
| Executor | Script path | `C:\scripts\zerto-receiver-notify.ps1` |
|
||||
| Data passing | JSON body to stdin | ✓ |
|
||||
| Run as | Identity | **Service** |
|
||||
| Response | Mode | **Async** |
|
||||
| Response | Timeout (sec) | `30` |
|
||||
| Response | Fail on non-zero exit | unticked *(async hooks have no caller to receive a 502)* |
|
||||
|
||||
### `zerto-post`
|
||||
|
||||
Same as above, except:
|
||||
|
||||
| Setting | Value |
|
||||
|---|---|
|
||||
| Slug | `zerto-post` |
|
||||
| Description | "Zerto post-recovery: notify + VM health check" |
|
||||
| Script path | a **wrapper** that calls both receiver scripts in turn (see below) |
|
||||
| Timeout (sec) | `120` |
|
||||
|
||||
Two receivers on one endpoint is easiest with a tiny wrapper that fans
|
||||
stdin out to both scripts:
|
||||
|
||||
```powershell
|
||||
# C:\scripts\zerto-post-fanout.ps1
|
||||
$body = [Console]::In.ReadToEnd()
|
||||
$body | & 'C:\scripts\zerto-receiver-notify.ps1'
|
||||
$body | & 'C:\scripts\zerto-receiver-vm-healthcheck.ps1'
|
||||
```
|
||||
|
||||
Or run the two as separate endpoints (`zerto-post-notify` and
|
||||
`zerto-post-healthcheck`) and have the Zerto-side script POST to both —
|
||||
either pattern is fine. The fanout wrapper keeps the Zerto config simpler.
|
||||
|
||||
## 4. Wire up the bearer token
|
||||
|
||||
On the ZVMA / scripts-service side, the easiest place to put the token is
|
||||
a Kubernetes Secret mounted into the pod, but the simplest approach for
|
||||
testing is to pass it as a parameter to the Zerto-side script:
|
||||
|
||||
> VPG settings → Pre-Recovery Script → Parameters:
|
||||
> `-Phase pre -Bearer <paste-token>`
|
||||
>
|
||||
> VPG settings → Post-Recovery Script → Parameters:
|
||||
> `-Phase post -Bearer <paste-token>`
|
||||
|
||||
For production, mount a Secret at a known path in the pod and have the
|
||||
sender script read from it (`Get-Content /run/secrets/webhook-token`).
|
||||
|
||||
## 5. Test before going live
|
||||
|
||||
Run a Test failover on a non-critical VPG. Watch:
|
||||
|
||||
- **Slack/Teams**: a `:test_tube: Zerto Test - phase: pre` message arrives,
|
||||
followed ~30s–several minutes later by a `:test_tube: Zerto Test - phase:
|
||||
post` message.
|
||||
- **Webhook Server GUI** → run history: two runs for `zerto-pre` /
|
||||
`zerto-post`, both green.
|
||||
- **`C:\ProgramData\WebhookServer\zerto-healthchecks\`**: a fresh JSON
|
||||
report named `<vpg>-Test-<utcstamp>.json` containing per-VM ping and port
|
||||
probe results.
|
||||
- **ZVMA**: the VPG operation completes successfully; nothing in the
|
||||
pre/post logs blocked on the webhook.
|
||||
|
||||
## Variations
|
||||
|
||||
### Branch on Test vs. real failover in the receivers
|
||||
|
||||
The notifier already styles the message differently. To do something only
|
||||
on a real failover (e.g. update DNS), guard with:
|
||||
|
||||
```powershell
|
||||
if ($p.zerto.operation -ne 'Test') {
|
||||
# do the destructive thing
|
||||
}
|
||||
```
|
||||
|
||||
A `ZertoOperation` of `Test` means "exercise — don't touch production
|
||||
dependencies." Always check it before doing anything that mutates real
|
||||
state.
|
||||
|
||||
### Capture `ZertoForce` from pre for use in post
|
||||
|
||||
`ZertoForce` is `Yes` only during the **pre** phase when force mode is on
|
||||
and is reset to `No` by the **post** phase. If your post-side logic needs
|
||||
to know the operation was force-flagged, save it during pre (e.g. write a
|
||||
small marker to the shared `ZertoOutputDir`) and read it back during post.
|
||||
|
||||
### Per-VPG endpoints
|
||||
|
||||
For fine-grained access control or different actions per VPG, create one
|
||||
endpoint per VPG (`zerto-pre-app01`, `zerto-post-app01`, …) with its own
|
||||
bearer token. Override `-WebhookUrl` and `-Bearer` on the Zerto side per
|
||||
VPG.
|
||||
|
||||
### Audit trail
|
||||
|
||||
Every endpoint can have an outbound **Callback** URL. Configure with your
|
||||
SIEM's HTTP collector + an HMAC secret, and every run produces a JSON
|
||||
record with runId, exit code, duration, stdout, and stderr — convenient
|
||||
for compliance.
|
||||
|
||||
## Security note
|
||||
|
||||
The ZVMA `scripts-service` pod runs your scripts inside a Linux container
|
||||
with broad reach into the management cluster — anything your script does
|
||||
runs with whatever ServiceAccount that pod uses. Treat the script content
|
||||
as privileged and make sure pre/post script edit rights are restricted to
|
||||
trusted operators. If you're unfamiliar with the pod's RBAC posture, check
|
||||
`Get-ChildItem Env:` from inside the container and look at
|
||||
`/var/run/secrets/kubernetes.io/serviceaccount/` — that token is what your
|
||||
scripts (and a malicious script) can use to talk to the K8s API.
|
||||
@@ -1,78 +0,0 @@
|
||||
# Run As modes — when to use which
|
||||
|
||||
Each endpoint has a **Run As** setting (in the editor's "Run as" section) that controls *who* the script runs as. The default works for most cases, and switching modes is one dropdown change.
|
||||
|
||||
## The three modes
|
||||
|
||||
| Mode | Runs as | Use when… |
|
||||
|---|---|---|
|
||||
| **Service** *(default)* | Whoever the Windows Service runs under (LocalSystem by default) | Almost everything. Local file ops, calling local APIs, running cmd / PowerShell scripts that don't need a user identity. |
|
||||
| **InteractiveUser** | The user logged in at the keyboard | The script needs to put a window on the screen (Calculator, a notification dialog, opening a browser tab) |
|
||||
| **SpecificUser** | A named local or domain user / password you provide | The script runs in AD, a fileshare, or any system that wants the action attributed to a specific identity — and you don't want the service itself running as that user. |
|
||||
|
||||
## Service (default)
|
||||
|
||||
Nothing to configure. The hook runs as `LocalSystem` by default — full local rights, very limited network identity (the machine account on a domain).
|
||||
|
||||
You can change the service identity at install time via the `-ServiceAccount` parameter to `install-service.ps1` (gMSA, domain user, etc.). Anything you set there applies to **all** Service-mode endpoints. See [Service account & Active Directory](service-account-and-ad.md).
|
||||
|
||||
**Pros**: zero config per endpoint, no passwords to manage, fastest path
|
||||
**Cons**: the script can't pop UI on the user's desktop (Session 0 isolation), and on a workgroup machine it has no domain identity at all
|
||||
|
||||
## InteractiveUser
|
||||
|
||||
Pick this when the hook should appear visually on the desktop of whoever is logged in. The clearest example is "fire a hook from my phone, get a Calculator window on my PC."
|
||||
|
||||
How it works internally: the service (running as SYSTEM) calls the Win32 API `WTSQueryUserToken` to grab the active console session's user token, then `CreateProcessAsUser` to land the new process inside that session.
|
||||
|
||||
What you don't have to configure: username, password, profile loading, session ID. All inferred at runtime.
|
||||
|
||||
What can go wrong:
|
||||
|
||||
- **No one logged in** at the keyboard → hook fails with `No active console session - is anyone logged in at the keyboard?`. The hook can't run; there's no desktop to land on.
|
||||
- **Service runs as anything other than LocalSystem** → `WTSQueryUserToken` requires SYSTEM. If you switched the service to a gMSA / domain user, InteractiveUser stops working.
|
||||
- **Locked desktop, no user logged in but session 1 reserved** → similar to "no one logged in." Once a user logs in interactively (even just to the lock screen with credentials cached), the session is "active enough" for this to work.
|
||||
|
||||
**Use case examples**: see [recipes/ui-on-desktop.md](recipes/ui-on-desktop.md).
|
||||
|
||||
## SpecificUser
|
||||
|
||||
Pick this when the hook needs to authenticate as a specific account — a service account with delegated AD rights, a local Administrator on a remote machine, etc. — but you don't want the *whole service* running as that account.
|
||||
|
||||
Configure:
|
||||
|
||||
- **Username**: `DOMAIN\user`, `.\local-user`, or a UPN like `user@contoso.com`. The leading `.\` is shorthand for the local machine.
|
||||
- **Password**: stored DPAPI-encrypted at rest. Visible in plaintext in the GUI for an admin user, by design — anyone with admin pipe access already has SYSTEM-equivalent rights.
|
||||
- **Load profile**: optional. Loads the user's HKCU and AppData before running. Slower (~1s extra). Only needed if the script reads user-scoped settings (uncommon).
|
||||
|
||||
How it works internally: the service calls `LogonUser` with the credentials (interactive logon type first, falls back to batch logon for service-only accounts), then `DuplicateTokenEx` + `CreateProcessAsUser`. The script lands in a fresh batch session with the user's network identity.
|
||||
|
||||
> **Why not `psi.UserName` / `psi.Password` like a normal .NET app?** Because `CreateProcessWithLogonW` (what those properties use under the hood) refuses to run when the caller is `LocalSystem`, which is exactly our scenario. The token-based path is the documented Windows mechanism for this.
|
||||
|
||||
What can go wrong:
|
||||
|
||||
- **Wrong password** → log shows `LogonUser (DOMAIN\user) failed - The user name or password is incorrect`. Re-enter in the editor.
|
||||
- **Account is denied logon locally** → log shows `Logon failure: the user has not been granted the requested logon type`. Make sure the account has at least one of *Log on as a batch job* or *Log on locally* under `secpol.msc` → Local Policies → User Rights Assignment.
|
||||
- **Domain controller unreachable** → for domain accounts, the service must be able to reach a DC. For local accounts (`.\name`), no domain dependency.
|
||||
|
||||
## Decision flowchart
|
||||
|
||||
```
|
||||
Need UI on the user's desktop?
|
||||
│
|
||||
┌─────── yes ─────┴────── no ─────┐
|
||||
│ │
|
||||
InteractiveUser Need specific identity (AD / fileshare / etc.)?
|
||||
│
|
||||
┌──── yes ────┴──── no ────┐
|
||||
│ │
|
||||
Should ALL hooks run as Service
|
||||
this identity?
|
||||
│
|
||||
┌────── yes ──────────┴───────── no ──────────┐
|
||||
│ │
|
||||
Run service itself SpecificUser per endpoint
|
||||
as that account
|
||||
(gMSA / domain user)
|
||||
see service-account-and-ad.md
|
||||
```
|
||||
@@ -1,149 +0,0 @@
|
||||
# Service account & Active Directory
|
||||
|
||||
The service runs as `LocalSystem` out of the box. That's right for local-only scripts and **read-only** AD queries (LocalSystem authenticates to the network as the machine account, which Authenticated Users includes by default). It is wrong for hooks that need to **modify** AD — passwords, group memberships, computer objects.
|
||||
|
||||
This page covers the four real-world choices and how to switch.
|
||||
|
||||
## The four options
|
||||
|
||||
| Account | Network identity | When to use |
|
||||
|---|---|---|
|
||||
| **`LocalSystem`** *(default)* | Computer account `DOMAIN\MACHINE$` on a domain-joined host; nothing on a workgroup host | Default. Local file ops, simple PowerShell, read-only AD queries. Most powerful local account — any hook running under it has full local rights. |
|
||||
| **`LocalService`** | None | **Don't.** Cannot talk to a domain controller. Listed only to rule it out. |
|
||||
| **`NetworkService`** | Same machine account as LocalSystem | Slightly less local privilege than LocalSystem, same network identity. Rarely the right pick. |
|
||||
| **Domain user** (`DOMAIN\svc-webhookserver`) | That user | Use when hooks need write access to AD and you can't use a gMSA. You own password rotation. |
|
||||
| **gMSA** (`DOMAIN\svc-webhookserver$`) | That gMSA | **Recommended for AD-write workloads.** AD generates and rotates the password automatically every 30 days. Requires domain functional level 2012+. |
|
||||
|
||||
## Switching the service account at install time
|
||||
|
||||
Pass `-ServiceAccount` to `install-service.ps1` (or to the deploy / dev launcher):
|
||||
|
||||
```powershell
|
||||
# Domain user
|
||||
& "C:\Program Files\WebhookServer\scripts\install-service.ps1" `
|
||||
-BinaryPath "C:\Program Files\WebhookServer\WebhookServer.Service.exe" `
|
||||
-ServiceAccount "CONTOSO\svc-webhookserver" -Password "..."
|
||||
|
||||
# gMSA - note trailing $ and no -Password
|
||||
& "C:\Program Files\WebhookServer\scripts\install-service.ps1" `
|
||||
-BinaryPath "C:\Program Files\WebhookServer\WebhookServer.Service.exe" `
|
||||
-ServiceAccount 'CONTOSO\svc-webhookserver$'
|
||||
```
|
||||
|
||||
Or do it manually with `sc.exe` if the service is already installed:
|
||||
|
||||
```powershell
|
||||
sc.exe stop WebhookServer
|
||||
sc.exe config WebhookServer obj= 'CONTOSO\svc-webhookserver$'
|
||||
sc.exe start WebhookServer
|
||||
```
|
||||
|
||||
## gMSA setup (recommended for AD writes)
|
||||
|
||||
A gMSA is a Group Managed Service Account. Active Directory generates and stores its password and rotates it every 30 days; the host machine account retrieves the password as needed. You never see or store it. This is the cleanest pattern for production.
|
||||
|
||||
### One-time domain setup
|
||||
|
||||
If your domain has never used gMSAs, create the KDS root key (only needed once per domain):
|
||||
|
||||
```powershell
|
||||
# from a Domain Admin PowerShell, on any DC
|
||||
Add-KdsRootKey -EffectiveImmediately
|
||||
# in production wait 10 hours for replication; in a lab, override:
|
||||
# Add-KdsRootKey -EffectiveTime ((Get-Date).AddHours(-10))
|
||||
```
|
||||
|
||||
### Create the gMSA
|
||||
|
||||
```powershell
|
||||
# from a DC, with AD PowerShell module loaded
|
||||
New-ADServiceAccount -Name svc-webhookserver `
|
||||
-DNSHostName webhook01.contoso.local `
|
||||
-PrincipalsAllowedToRetrieveManagedPassword "DOMAIN\WebhookHosts"
|
||||
```
|
||||
|
||||
`PrincipalsAllowedToRetrieveManagedPassword` is the security group containing the computer accounts allowed to use the gMSA. Add your webhook host(s) to that group:
|
||||
|
||||
```powershell
|
||||
Add-ADGroupMember -Identity 'WebhookHosts' -Members 'WEBHOOK01$'
|
||||
# the host needs to reboot OR have its kerberos ticket flushed for the new group membership to apply
|
||||
```
|
||||
|
||||
### Install the gMSA on the host
|
||||
|
||||
On the webhook server machine itself:
|
||||
|
||||
```powershell
|
||||
# from elevated PowerShell, AD PowerShell module installed (RSAT)
|
||||
Install-ADServiceAccount svc-webhookserver
|
||||
Test-ADServiceAccount svc-webhookserver # should return True
|
||||
```
|
||||
|
||||
If `Test-ADServiceAccount` returns False, check:
|
||||
|
||||
- Host is in the `WebhookHosts` group (or whoever's in `PrincipalsAllowedToRetrieveManagedPassword`)
|
||||
- Host has been rebooted since being added to the group
|
||||
- KDS root key has had time to propagate (10 hours by default)
|
||||
|
||||
### Configure the service to use it
|
||||
|
||||
```powershell
|
||||
# from elevated PowerShell on the webhook host
|
||||
sc.exe stop WebhookServer
|
||||
sc.exe config WebhookServer obj= 'CONTOSO\svc-webhookserver$'
|
||||
sc.exe start WebhookServer
|
||||
```
|
||||
|
||||
Note the trailing `$`. There is **no password parameter** for gMSAs. The trailing `$` is what tells the SCM "look up this account in AD as a managed service account, retrieve its password automatically."
|
||||
|
||||
### Grant AD permissions
|
||||
|
||||
Give the gMSA only what it needs. For a typical "reset user passwords" workload:
|
||||
|
||||
```powershell
|
||||
# Delegate "Reset password and force change at next logon" on a specific OU
|
||||
$ou = "OU=Standard Users,DC=contoso,DC=local"
|
||||
dsacls $ou /I:S /G "CONTOSO\svc-webhookserver$:CA;Reset Password;user"
|
||||
dsacls $ou /I:S /G "CONTOSO\svc-webhookserver$:WP;pwdLastSet;user"
|
||||
```
|
||||
|
||||
…or use the GUI Delegation of Control wizard in Active Directory Users and Computers.
|
||||
|
||||
## Domain user (fallback when gMSA isn't available)
|
||||
|
||||
```powershell
|
||||
# 1. Create the user (one time)
|
||||
New-ADUser -Name "svc-webhookserver" -SamAccountName "svc-webhookserver" `
|
||||
-AccountPassword (Read-Host -AsSecureString "password") -Enabled $true `
|
||||
-PasswordNeverExpires $true -CannotChangePassword $true
|
||||
|
||||
# 2. Grant "Log on as a service" right on the host:
|
||||
# secpol.msc -> Local Policies -> User Rights Assignment -> Log on as a service
|
||||
# Add CONTOSO\svc-webhookserver
|
||||
|
||||
# 3. Configure the service:
|
||||
sc.exe config WebhookServer obj= "CONTOSO\svc-webhookserver" password= "..."
|
||||
```
|
||||
|
||||
You own password rotation. When you change the password in AD, also update the service via `sc.exe config WebhookServer password= "newpw"` and restart it.
|
||||
|
||||
## What changes for hooks when you switch the service account
|
||||
|
||||
- **Service mode hooks** now run as the new account. PowerShell `whoami` from inside a hook will show the new identity.
|
||||
- **InteractiveUser hooks stop working** if you switch off LocalSystem. Only SYSTEM can call `WTSQueryUserToken`. If you need both AD-write hooks and UI-on-desktop hooks, pick one of:
|
||||
- Keep service as LocalSystem and use **SpecificUser** mode for AD-write hooks
|
||||
- Switch service to a gMSA / domain user and drop UI hooks (or move them to a separate Webhook Server instance running as LocalSystem)
|
||||
- **SpecificUser hooks** continue to work regardless. They use a separate `LogonUser` token per call.
|
||||
|
||||
## Verifying the switch worked
|
||||
|
||||
After changing the service account, restart the service and add a quick diagnostic endpoint:
|
||||
|
||||
```
|
||||
slug: whoami
|
||||
auth: none
|
||||
executor: Windows PowerShell
|
||||
inline command: whoami; whoami /groups
|
||||
```
|
||||
|
||||
Hit it and verify the output matches the account you configured. The first line should be `domain\svc-webhookserver` (or `domain\machine$` for LocalSystem on a domain-joined host).
|
||||
@@ -1,158 +0,0 @@
|
||||
# Troubleshooting
|
||||
|
||||
This page indexes the most common ways things go wrong, where to look, and what to do.
|
||||
|
||||
## Where to look first
|
||||
|
||||
| Symptom | First check |
|
||||
|---|---|
|
||||
| GUI shows "Disconnected" | Service running? `Get-Service WebhookServer` |
|
||||
| Hook returns 404 | Slug typo, or endpoint disabled |
|
||||
| Hook returns 401 | Auth header / signature mismatch |
|
||||
| Hook returns 403 | IP allowlist denies the caller |
|
||||
| Hook returns 200 but nothing happens | Response is the script's stdout — check exit code, stderr |
|
||||
| Hook returns 502 | Script ran and exited non-zero. Body has stderr. |
|
||||
| Hook returns 500 | Launch error (script not found, invalid path) |
|
||||
| Hook hangs | Timeout reached, or script is waiting on stdin |
|
||||
| Calc / UI doesn't appear despite InteractiveUser | See [Run As modes](runas-modes.md) — common pitfalls |
|
||||
|
||||
## Where the logs are
|
||||
|
||||
`C:\ProgramData\WebhookServer\logs\webhook-YYYYMMDD.log` — daily rolling, 14-day retention by default.
|
||||
|
||||
Every webhook run logs:
|
||||
- `[INF] Run <id> <slug> ok exit=0 dur=<ms>ms stdout=...` on success
|
||||
- `[WRN] Run <id> <slug> non-zero exit=<n> dur=<ms>ms stdout=... stderr=...` on script failure
|
||||
- `[WRN] Run <id> <slug> failed to launch: <reason>` on launch failure
|
||||
- `[WRN] Run <id> <slug> timed out after <s>s; process killed` on timeout
|
||||
|
||||
The GUI's bottom panel auto-refreshes the same log file every 3 seconds. Tick the **Auto-scroll** checkbox to keep it pinned to the latest line.
|
||||
|
||||
## Common issues
|
||||
|
||||
### "Disconnected: Access to the path is denied" right after install
|
||||
|
||||
You launched the GUI without elevation. The admin pipe ACL is `SYSTEM` + `Administrators`-full-control; UAC token splitting denies the standard token.
|
||||
|
||||
**Fix in v0.1.1+**: nothing — the GUI's manifest is `requireAdministrator` and Start Menu / shortcut launches auto-elevate.
|
||||
|
||||
**Fix in v0.1.0**: right-click the Start Menu shortcut → **Run as administrator**, or upgrade.
|
||||
|
||||
### Service won't start after install / GUI says "Disconnected" with no obvious error
|
||||
|
||||
If `Get-Service WebhookServer` shows it stopped and `Start-Service WebhookServer` fails, or the GUI itself won't even launch, you're probably missing a .NET 8 runtime. The v0.1.4+ installer auto-fetches them, but a clean Windows Server box might still hit this if the install was offline or used an older installer.
|
||||
|
||||
Check what's installed:
|
||||
|
||||
```powershell
|
||||
dotnet --list-runtimes
|
||||
```
|
||||
|
||||
You need both:
|
||||
|
||||
- `Microsoft.AspNetCore.App 8.x.y` — for the Service
|
||||
- `Microsoft.WindowsDesktop.App 8.x.y` — for the GUI
|
||||
|
||||
If either is missing, install from:
|
||||
|
||||
- ASP.NET Core 8 Runtime — <https://aka.ms/dotnet/8.0/aspnetcore-runtime-win-x64.exe>
|
||||
- .NET Desktop Runtime 8 — <https://aka.ms/dotnet/8.0/windowsdesktop-runtime-win-x64.exe>
|
||||
|
||||
Re-run with `/install /quiet /norestart` for unattended installs. Then `Start-Service WebhookServer`.
|
||||
|
||||
### "Connection refused" hitting the hook URL
|
||||
|
||||
Three possibilities, in order of probability:
|
||||
|
||||
1. **Service stopped.** `Get-Service WebhookServer` and `Start-Service WebhookServer` if needed.
|
||||
2. **Wrong port.** Default is 8080. Check **Server → Settings → HTTP port** in the GUI, or `netstat -an | findstr :8080`.
|
||||
3. **Bound to a specific NIC and you're calling on another.** Check **Server → Settings → Listen on**. If "Listen on all interfaces" is unchecked and you only ticked LAN IPs, calls to `localhost` may fail. Tick `127.0.0.1` too.
|
||||
|
||||
### Hook works from `localhost` but not from another machine on the LAN
|
||||
|
||||
Windows Firewall. The installer doesn't add a firewall rule (intentional — you should choose your scope). Add one:
|
||||
|
||||
```powershell
|
||||
# from elevated PowerShell on the webhook host
|
||||
New-NetFirewallRule -DisplayName "Webhook Server HTTP 8080" -Direction Inbound `
|
||||
-Action Allow -Protocol TCP -LocalPort 8080 -Profile Domain,Private
|
||||
```
|
||||
|
||||
Use `-Profile Public` only if you really mean it. Better: front the server with a reverse proxy and don't expose 8080 directly.
|
||||
|
||||
### `[WRN] Run … failed to launch: launch error: An error occurred trying to start process 'X'. Access is denied.`
|
||||
|
||||
Likely **SpecificUser mode + `psi.UserName`** failure. Should be impossible in v0.1.1+ (we use `LogonUser` + `CreateProcessAsUser` directly). If you see this on v0.1.1, double-check the version: `Get-Item "C:\Program Files\WebhookServer\WebhookServer.Service.exe" | % VersionInfo`.
|
||||
|
||||
### `[WRN] Run … failed to launch: LogonUser (DOMAIN\user) failed`
|
||||
|
||||
The credentials don't authenticate. Common causes:
|
||||
|
||||
- Typo in the password (paste it back into the GUI to verify; the field is plaintext for an admin user)
|
||||
- Account locked / disabled / expired
|
||||
- The account is denied the right logon types — check `secpol.msc` → Local Policies → User Rights Assignment → "Deny logon as a batch job" / "Deny logon locally"
|
||||
- For domain accounts: the host can't reach a DC
|
||||
|
||||
### `non-zero exit=-1073741502` (`0xC0000142` STATUS_DLL_INIT_FAILED)
|
||||
|
||||
The new process couldn't initialize. With **InteractiveUser** mode this means we tried to open `winsta0\default` and the user's session token doesn't have access (e.g., no one's logged in). With **SpecificUser** this should not occur in v0.1.1+ — we deliberately don't set lpDesktop for that mode.
|
||||
|
||||
### Hook returns 502 with empty stdout/stderr
|
||||
|
||||
The script's exit was non-zero but it didn't print anything. PowerShell's `$ErrorActionPreference = 'Stop'` is your friend — turn it on at the top of the script and any cmdlet failure becomes terminating with a clear message in stderr.
|
||||
|
||||
### "ServiceState: ListenerSettingsChanged" → service restart
|
||||
|
||||
After saving Server Settings with a port or HTTPS change, the service stops itself so the SCM restarts it on the new bindings. The GUI briefly shows "Disconnected" then reconnects. If it doesn't reconnect within ~10 seconds:
|
||||
|
||||
```powershell
|
||||
Get-Service WebhookServer | Format-List Status, StartType
|
||||
```
|
||||
|
||||
If the service is in `Stopped`, the SCM didn't restart it (failure-recovery only kicks in on *abnormal* termination, and a clean stop doesn't qualify). Manual:
|
||||
|
||||
```powershell
|
||||
Start-Service WebhookServer
|
||||
```
|
||||
|
||||
### GUI editor changes don't seem to take effect
|
||||
|
||||
After saving an endpoint, the service loads the new config in memory immediately — no restart needed. If a hook is mid-run when you save, that run finishes against the OLD config; the new config applies to subsequent runs.
|
||||
|
||||
If the GUI's grid still shows old values, hit any other endpoint or wait for the 3-second poll to refresh the display.
|
||||
|
||||
### Tray icon doesn't appear
|
||||
|
||||
Check whether the GUI is running: `Get-Process WebhookServer.Gui`. If not, the tray icon doesn't exist (it's part of the GUI process). To have a persistent tray independent of the main window, leave the GUI running and minimize it — it'll hide-to-tray rather than truly close.
|
||||
|
||||
To run the GUI minimized at login: create a Windows shortcut to `WebhookServer.Gui.exe`, set "Run" to "Minimized" in the shortcut properties, and put it in your user's Startup folder (`shell:startup`). The auto-elevate manifest still takes effect.
|
||||
|
||||
## Getting useful logs from a script
|
||||
|
||||
Inside your hook scripts, write to stderr for diagnostic info — Webhook Server logs stderr separately from stdout, and stderr is preserved even on success:
|
||||
|
||||
```powershell
|
||||
[Console]::Error.WriteLine("processing item $i of $total")
|
||||
```
|
||||
|
||||
Or use `Write-Error` which produces non-fatal errors:
|
||||
|
||||
```powershell
|
||||
Write-Error "skipping bogus input" # stderr but doesn't terminate
|
||||
```
|
||||
|
||||
The full stderr appears in the log line for the run, plus in the response body for sync calls.
|
||||
|
||||
## Asking for help
|
||||
|
||||
If you're stuck, file an issue at:
|
||||
|
||||
> https://github.com/recklessop/webhook-server/issues
|
||||
|
||||
Include:
|
||||
|
||||
- Webhook Server version (Help → About, or the file version of the `.exe`)
|
||||
- Windows version (`winver`)
|
||||
- The slug + relevant bits of the endpoint config (NOT the secrets)
|
||||
- The log lines for the failing run (search for the runId)
|
||||
- What you expected vs. what happened
|
||||
@@ -1,90 +0,0 @@
|
||||
# Uninstalling
|
||||
|
||||
## TL;DR
|
||||
|
||||
**Settings → Apps & features → Webhook Server → Uninstall.** Or right-click the **Uninstall Webhook Server** Start Menu shortcut.
|
||||
|
||||
Your endpoints, secrets, and logs in `C:\ProgramData\WebhookServer\` are preserved by default. To wipe those too, see [Below](#wiping-config-and-logs-too).
|
||||
|
||||
## What the uninstaller does
|
||||
|
||||
In order:
|
||||
|
||||
1. **Stops the service** (`net stop WebhookServer`).
|
||||
2. **Removes the service** registration via `uninstall-service.ps1` (which calls `sc.exe delete WebhookServer`).
|
||||
3. **Deletes** `C:\Program Files\WebhookServer\`.
|
||||
4. **Removes** the Start Menu and (if created) Desktop shortcuts.
|
||||
5. **Removes** the Programs and Features entry.
|
||||
|
||||
What it **does not** touch:
|
||||
|
||||
- `C:\ProgramData\WebhookServer\` (config, secrets, log files, auto-snapshots)
|
||||
- Any cert in your local cert store you bound HTTPS to
|
||||
- Domain accounts / gMSAs the service ran under
|
||||
- Endpoints' deployed scripts, if you stored them outside the install dir
|
||||
|
||||
## Wiping config and logs too
|
||||
|
||||
After running the uninstaller, also remove the data root:
|
||||
|
||||
```powershell
|
||||
# from elevated PowerShell
|
||||
Remove-Item -Recurse -Force "$env:ProgramData\WebhookServer"
|
||||
```
|
||||
|
||||
This deletes:
|
||||
|
||||
- `config.json` (with all your endpoints, encrypted secrets, settings)
|
||||
- `backups\` (all auto-snapshots — you can't restore from these once gone)
|
||||
- `logs\` (history of every webhook hit)
|
||||
|
||||
There's no recovery from this. If you might want to reinstall later with the same configuration, copy `config.json` to a safe location first. Note that **secrets in the saved config can only be decrypted on the same machine** (DPAPI LocalMachine scope) — you can move the file but the bearer/HMAC/RunAs passwords inside become unrecoverable on a different host.
|
||||
|
||||
## Silent uninstall
|
||||
|
||||
The Programs and Features uninstaller is `unins000.exe` in the install directory:
|
||||
|
||||
```powershell
|
||||
# from elevated PowerShell
|
||||
& "C:\Program Files\WebhookServer\unins000.exe" /VERYSILENT /SUPPRESSMSGBOXES /NORESTART
|
||||
```
|
||||
|
||||
Same set of preserved/removed paths as the interactive flow.
|
||||
|
||||
## Removing only the service, keeping the binaries
|
||||
|
||||
If you want to keep the GUI installed but stop running the service (rare, but useful if you're testing):
|
||||
|
||||
```powershell
|
||||
# from elevated PowerShell
|
||||
sc.exe stop WebhookServer
|
||||
sc.exe delete WebhookServer
|
||||
```
|
||||
|
||||
The GUI will show **Disconnected** since there's no service to talk to. Re-create the service later by running `install-service.ps1`:
|
||||
|
||||
```powershell
|
||||
& "C:\Program Files\WebhookServer\scripts\install-service.ps1" `
|
||||
-BinaryPath "C:\Program Files\WebhookServer\WebhookServer.Service.exe"
|
||||
```
|
||||
|
||||
## Edge cases
|
||||
|
||||
### "The service cannot be stopped because it has not been started."
|
||||
|
||||
Harmless. The uninstaller proceeds regardless.
|
||||
|
||||
### "Cannot delete: file in use"
|
||||
|
||||
A GUI window or other process is holding files in `C:\Program Files\WebhookServer\` open. Close everything and re-run the uninstaller. If that fails, reboot and re-run.
|
||||
|
||||
### Programs and Features entry remains after files are gone
|
||||
|
||||
If you deleted `C:\Program Files\WebhookServer\` manually before running the uninstaller, `unins000.exe` is gone too and Programs and Features can't run it. Remove the orphan entry by deleting its registry key:
|
||||
|
||||
```powershell
|
||||
# from elevated PowerShell - dry run to confirm the key exists
|
||||
Get-Item 'HKLM:\Software\Microsoft\Windows\CurrentVersion\Uninstall\{6E3B3C1A-9C20-4F50-B6A8-2B6D6D7E2F11}_is1' -ErrorAction SilentlyContinue
|
||||
# if it shows up, delete it:
|
||||
Remove-Item 'HKLM:\Software\Microsoft\Windows\CurrentVersion\Uninstall\{6E3B3C1A-9C20-4F50-B6A8-2B6D6D7E2F11}_is1' -Recurse
|
||||
```
|
||||
@@ -1,76 +0,0 @@
|
||||
# Upgrading
|
||||
|
||||
## TL;DR
|
||||
|
||||
Download the new installer from [Releases](https://github.com/recklessop/webhook-server/releases/latest) and run it. That's it. Your config, endpoints, secrets, and logs are preserved.
|
||||
|
||||
## What the upgrade does
|
||||
|
||||
The Inno Setup installer detects an existing install and runs through these steps automatically:
|
||||
|
||||
1. **`net stop WebhookServer`** — synchronously stops the running service so its binaries are unlocked. Blocks until the SCM reports the service is actually stopped.
|
||||
2. **`taskkill /f /im WebhookServer.Gui.exe`** — closes the GUI if you left it running. Same for any orphan `WebhookServer.Service.exe` from a `deploy.ps1` dev install.
|
||||
3. **Copies** the new binaries into `C:\Program Files\WebhookServer\`. Files marked `ignoreversion` so newer files always overwrite older ones, even if version metadata happens to match.
|
||||
4. **Re-registers** the service via `install-service.ps1`, which detects the existing `WebhookServer` service via `Get-Service` and takes the **update** branch (changes the binary path) rather than re-creating it. Your service account choice is preserved.
|
||||
5. **Starts the service**. The GUI launches if you left the post-install checkbox ticked.
|
||||
|
||||
Total downtime for the service: 2–10 seconds depending on disk speed and how long the service takes to flush its log buffer.
|
||||
|
||||
## What's preserved
|
||||
|
||||
- `C:\ProgramData\WebhookServer\config.json` — the installer never touches this directory
|
||||
- All endpoints, secrets, callback URLs, allowlists
|
||||
- Bind addresses, display host, HTTPS binding settings
|
||||
- Auto-snapshots in `C:\ProgramData\WebhookServer\backups\`
|
||||
- Log files in `C:\ProgramData\WebhookServer\logs\`
|
||||
- The Windows Service identity (LocalSystem, gMSA, domain user — whatever you configured)
|
||||
|
||||
## What gets replaced
|
||||
|
||||
- Everything in `C:\Program Files\WebhookServer\` — the .exe files, .dll files, the icon, `install-service.ps1`, `uninstall-service.ps1`, the bundled `README.md`, the `docs/` folder
|
||||
|
||||
## Silent upgrades (Group Policy / SCCM / Intune / Ansible)
|
||||
|
||||
Same as the silent install:
|
||||
|
||||
```powershell
|
||||
WebhookServer-Setup-X.Y.Z.exe /VERYSILENT /SUPPRESSMSGBOXES /NORESTART
|
||||
```
|
||||
|
||||
The pre-install `net stop` step still fires; downtime is unchanged.
|
||||
|
||||
## Rolling back to a previous version
|
||||
|
||||
The installer doesn't support side-by-side versions or downgrade detection. To roll back:
|
||||
|
||||
1. Uninstall the current version (Settings → Apps, or `Start Menu → Webhook Server → Uninstall`). This stops + removes the service. Your config in `C:\ProgramData\WebhookServer\` is preserved.
|
||||
2. Run the older installer.
|
||||
|
||||
If a config field changed semantics between versions and you ran on the new version first, the **Config Checkpoints** menu (File → Config Checkpoints) lists snapshots taken before each save. The auto-snapshot from immediately before the upgrade is the closest you'll have to your pre-upgrade config.
|
||||
|
||||
## Edge cases
|
||||
|
||||
### "Setup cannot continue. Please close the following applications: WebhookServer.Gui.exe"
|
||||
|
||||
The taskkill step normally handles this, but if you're running an unusually slow process or if the GUI was elevated by a different user, you may see this. Close the GUI manually and click Retry.
|
||||
|
||||
### Service stays in a "Stopping" state forever
|
||||
|
||||
`net stop` waits up to 30 seconds for the service to stop. If a hook script hung (e.g. interactive prompt) and the service can't kill it cleanly, the SCM gives up and the install continues, but the service may end up in a bad state. Recovery:
|
||||
|
||||
```powershell
|
||||
# from elevated PowerShell
|
||||
Stop-Service WebhookServer -Force
|
||||
# if that fails:
|
||||
Get-WmiObject Win32_Service -Filter "Name='WebhookServer'" | ForEach-Object { Stop-Process -Id $_.ProcessId -Force }
|
||||
```
|
||||
|
||||
…then re-run the installer.
|
||||
|
||||
### Upgrade from a `deploy.ps1` dev install to an installer-managed install
|
||||
|
||||
The first time you run the installer on a machine that previously used `deploy.ps1`, the installer thinks it's doing a fresh install (no `Programs and Features` registry entry). It still detects the existing service and updates it cleanly, so the only visible difference is that **a Programs and Features entry now exists** for "Webhook Server" with `Justin Paul` as publisher. Future upgrades take the proper upgrade path.
|
||||
|
||||
### `deploy.ps1` after an installer-managed install
|
||||
|
||||
`deploy.ps1` is the dev workflow. It publishes from source and copies binaries to the same install location. Running it on top of an installer-managed install will overwrite the binaries but won't deregister the installer. If you then uninstall via Programs and Features, the uninstaller may leave files behind that `deploy.ps1` introduced. Pick one workflow and stick with it.
|
||||
@@ -55,9 +55,7 @@ Source: "{#RepoRoot}publish\service\*"; DestDir: "{app}"; Flags: ignoreversion r
|
||||
Source: "{#RepoRoot}publish\gui\*"; DestDir: "{app}"; Flags: ignoreversion recursesubdirs createallsubdirs
|
||||
Source: "{#RepoRoot}scripts\install-service.ps1"; DestDir: "{app}\scripts"; Flags: ignoreversion
|
||||
Source: "{#RepoRoot}scripts\uninstall-service.ps1"; DestDir: "{app}\scripts"; Flags: ignoreversion
|
||||
Source: "{#RepoRoot}scripts\examples\*"; DestDir: "{app}\scripts\examples"; Flags: ignoreversion recursesubdirs createallsubdirs
|
||||
Source: "{#RepoRoot}README.md"; DestDir: "{app}"; Flags: ignoreversion
|
||||
Source: "{#RepoRoot}docs\*"; DestDir: "{app}\docs"; Flags: ignoreversion recursesubdirs createallsubdirs
|
||||
Source: "{#RepoRoot}resources\webhook-server.ico"; DestDir: "{app}"; Flags: ignoreversion
|
||||
|
||||
[Icons]
|
||||
@@ -70,14 +68,9 @@ Filename: "powershell.exe"; \
|
||||
Parameters: "-NoProfile -ExecutionPolicy Bypass -File ""{app}\scripts\install-service.ps1"" -BinaryPath ""{app}\{#ServiceExeName}"""; \
|
||||
StatusMsg: "Installing Windows Service..."; \
|
||||
Flags: runhidden
|
||||
; Post-install GUI launch. The GUI's app.manifest is requireAdministrator,
|
||||
; so launching with shellexec (ShellExecute) honors the manifest and triggers
|
||||
; a clean UAC prompt. Using plain CreateProcess via the default Run path
|
||||
; would skip the manifest and result in an un-elevated GUI that cannot connect
|
||||
; to the admin pipe.
|
||||
Filename: "{app}\{#AppExeName}"; \
|
||||
Description: "Launch {#AppName}"; \
|
||||
Flags: postinstall nowait shellexec skipifsilent
|
||||
Flags: postinstall nowait skipifsilent
|
||||
|
||||
[UninstallRun]
|
||||
Filename: "powershell.exe"; \
|
||||
@@ -86,17 +79,6 @@ Filename: "powershell.exe"; \
|
||||
RunOnceId: "RemoveWebhookService"
|
||||
|
||||
[Code]
|
||||
const
|
||||
// aka.ms redirects to the latest 8.0.x patch. Inno Setup's downloader
|
||||
// follows redirects via the Windows HTTP stack.
|
||||
AspNetCore8Url = 'https://aka.ms/dotnet/8.0/aspnetcore-runtime-win-x64.exe';
|
||||
WinDesktop8Url = 'https://aka.ms/dotnet/8.0/windowsdesktop-runtime-win-x64.exe';
|
||||
AspNetCore8File = 'aspnetcore-runtime-8.0-win-x64.exe';
|
||||
WinDesktop8File = 'windowsdesktop-runtime-8.0-win-x64.exe';
|
||||
|
||||
var
|
||||
DownloadPage: TDownloadWizardPage;
|
||||
|
||||
function ServiceExists(): Boolean;
|
||||
var
|
||||
ResultCode: Integer;
|
||||
@@ -107,119 +89,6 @@ begin
|
||||
Result := (ResultCode = 0);
|
||||
end;
|
||||
|
||||
// True if a Microsoft.* shared-framework directory under
|
||||
// %ProgramFiles%\dotnet\shared contains at least one 8.x.y subfolder.
|
||||
function HasDotNet8(const RuntimeName: String): Boolean;
|
||||
var
|
||||
rec: TFindRec;
|
||||
base: String;
|
||||
begin
|
||||
Result := False;
|
||||
base := ExpandConstant('{commonpf}\dotnet\shared\') + RuntimeName;
|
||||
if not DirExists(base) then Exit;
|
||||
if FindFirst(base + '\8.*', rec) then
|
||||
try
|
||||
repeat
|
||||
if (rec.Name <> '.') and (rec.Name <> '..') and
|
||||
DirExists(base + '\' + rec.Name) then begin
|
||||
Result := True;
|
||||
Exit;
|
||||
end;
|
||||
until not FindNext(rec);
|
||||
finally
|
||||
FindClose(rec);
|
||||
end;
|
||||
end;
|
||||
|
||||
function NeedsAspNet8(): Boolean;
|
||||
begin
|
||||
Result := not HasDotNet8('Microsoft.AspNetCore.App');
|
||||
end;
|
||||
|
||||
function NeedsWinDesktop8(): Boolean;
|
||||
begin
|
||||
Result := not HasDotNet8('Microsoft.WindowsDesktop.App');
|
||||
end;
|
||||
|
||||
procedure InitializeWizard;
|
||||
begin
|
||||
DownloadPage := CreateDownloadPage(
|
||||
'Downloading prerequisites',
|
||||
'Webhook Server needs the .NET 8 runtimes. Setup is fetching them now.',
|
||||
nil);
|
||||
end;
|
||||
|
||||
// Runs a downloaded runtime installer silently. Treats Microsoft's
|
||||
// "success but reboot pending" / "newer already installed" exit codes
|
||||
// as successes so we don't fail the whole install over a benign result.
|
||||
function RunRuntimeInstaller(const FileName, DisplayName: String): String;
|
||||
var
|
||||
resultCode: Integer;
|
||||
fullPath: String;
|
||||
begin
|
||||
Result := '';
|
||||
fullPath := ExpandConstant('{tmp}\') + FileName;
|
||||
if not Exec(fullPath, '/install /quiet /norestart', '', SW_HIDE,
|
||||
ewWaitUntilTerminated, resultCode) then begin
|
||||
Result := 'Could not launch the ' + DisplayName + ' installer.';
|
||||
Exit;
|
||||
end;
|
||||
case resultCode of
|
||||
0, 1638, 3010, 1641: ;
|
||||
else
|
||||
Result := DisplayName + ' installer failed (exit code ' +
|
||||
IntToStr(resultCode) + ').';
|
||||
end;
|
||||
end;
|
||||
|
||||
function NextButtonClick(CurPageID: Integer): Boolean;
|
||||
var
|
||||
errMsg: String;
|
||||
begin
|
||||
Result := True;
|
||||
if CurPageID <> wpReady then Exit;
|
||||
if not (NeedsAspNet8 or NeedsWinDesktop8) then Exit;
|
||||
|
||||
DownloadPage.Clear;
|
||||
if NeedsAspNet8 then
|
||||
DownloadPage.Add(AspNetCore8Url, AspNetCore8File, '');
|
||||
if NeedsWinDesktop8 then
|
||||
DownloadPage.Add(WinDesktop8Url, WinDesktop8File, '');
|
||||
DownloadPage.Show;
|
||||
try
|
||||
try
|
||||
DownloadPage.Download;
|
||||
except
|
||||
if MsgBox('Failed to download the .NET 8 runtimes:' + #13#10#13#10 +
|
||||
GetExceptionMessage + #13#10#13#10 +
|
||||
'Continue installing anyway? Webhook Server will not start ' +
|
||||
'until the runtimes are installed manually.',
|
||||
mbError, MB_YESNO) = IDNO then
|
||||
Result := False;
|
||||
Exit;
|
||||
end;
|
||||
finally
|
||||
DownloadPage.Hide;
|
||||
end;
|
||||
|
||||
if NeedsAspNet8 then begin
|
||||
errMsg := RunRuntimeInstaller(AspNetCore8File, 'ASP.NET Core 8 Runtime');
|
||||
if errMsg <> '' then begin
|
||||
MsgBox(errMsg, mbError, MB_OK);
|
||||
Result := False;
|
||||
Exit;
|
||||
end;
|
||||
end;
|
||||
if NeedsWinDesktop8 then begin
|
||||
errMsg := RunRuntimeInstaller(WinDesktop8File, '.NET Desktop Runtime 8');
|
||||
if errMsg <> '' then begin
|
||||
MsgBox(errMsg, mbError, MB_OK);
|
||||
Result := False;
|
||||
Exit;
|
||||
end;
|
||||
end;
|
||||
end;
|
||||
|
||||
function PrepareToInstall(var NeedsRestart: Boolean): String;
|
||||
var
|
||||
ResultCode: Integer;
|
||||
|
||||
+3
-138
@@ -53,150 +53,15 @@ if ($LASTEXITCODE -ne 0) { throw 'service publish failed' }
|
||||
-c $Configuration -r win-x64 --self-contained false -o $publishGui | Out-Host
|
||||
if ($LASTEXITCODE -ne 0) { throw 'GUI publish failed' }
|
||||
|
||||
# 2. Pre-flight: confirm every source path the .iss references exists, and
|
||||
# surface the longest path so MAX_PATH issues are obvious in the log.
|
||||
function Show-SourcePath($label, $path, [switch]$Recursive) {
|
||||
if (-not (Test-Path $path)) { Write-Warning "MISSING $label : $path"; return }
|
||||
$items = if ($Recursive) {
|
||||
Get-ChildItem $path -Recurse -File -ErrorAction SilentlyContinue
|
||||
} else {
|
||||
Get-ChildItem $path -File -ErrorAction SilentlyContinue
|
||||
}
|
||||
$count = ($items | Measure-Object).Count
|
||||
$longest = ($items | Measure-Object -Maximum -Property { $_.FullName.Length }).Maximum
|
||||
Write-Host (" {0,-30} files={1,-5} longestPath={2,-5} root={3}" -f $label, $count, $longest, $path)
|
||||
}
|
||||
|
||||
Write-Host ""
|
||||
Write-Host "--- pre-flight: source paths the .iss will read ---" -ForegroundColor Cyan
|
||||
Show-SourcePath 'publish\service' $publishSvc -Recursive
|
||||
Show-SourcePath 'publish\gui' $publishGui -Recursive
|
||||
Show-SourcePath 'scripts' (Join-Path $repoRoot 'scripts')
|
||||
Show-SourcePath 'scripts\examples' (Join-Path $repoRoot 'scripts\examples') -Recursive
|
||||
Show-SourcePath 'docs' (Join-Path $repoRoot 'docs') -Recursive
|
||||
Show-SourcePath 'resources' (Join-Path $repoRoot 'resources')
|
||||
Show-SourcePath 'README.md (file)' (Join-Path $repoRoot 'README.md')
|
||||
|
||||
$lpe = (Get-ItemProperty 'HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem' `
|
||||
-Name LongPathsEnabled -ErrorAction SilentlyContinue).LongPathsEnabled
|
||||
Write-Host " LongPathsEnabled (HKLM): $lpe"
|
||||
Write-Host ""
|
||||
|
||||
# 3. Compile installer.
|
||||
# 2. Compile installer.
|
||||
$iscc = Find-InnoCompiler
|
||||
$iss = Join-Path $repoRoot 'installer\webhook-server.iss'
|
||||
$dist = Join-Path $repoRoot 'dist'
|
||||
New-Item -ItemType Directory -Path $dist -Force | Out-Null
|
||||
|
||||
Write-Host "Compiling installer with $iscc"
|
||||
# Run ISCC from the .iss directory with just the bare filename. When invoked
|
||||
# with a deeply-nested absolute path on the act-runner host (under
|
||||
# %SystemRoot%\System32\config\systemprofile\...), ISCC sometimes prints a
|
||||
# generic "The system cannot find the path specified." before it touches any
|
||||
# source files. cd-ing first sidesteps it.
|
||||
$issDir = Split-Path $iss -Parent
|
||||
$issName = Split-Path $iss -Leaf
|
||||
|
||||
# Extra pre-flight: confirm the specific files our .iss references that a
|
||||
# trivial test .iss wouldn't (icon, README, scripts) actually exist relative
|
||||
# to the .iss directory the way ISCC will resolve them (RepoRoot = ..\).
|
||||
Write-Host "--- pre-flight: paths the .iss references via {#RepoRoot} ---" -ForegroundColor Cyan
|
||||
$issRefs = @(
|
||||
'resources\webhook-server.ico',
|
||||
'README.md',
|
||||
'scripts\install-service.ps1',
|
||||
'scripts\uninstall-service.ps1',
|
||||
'publish\service',
|
||||
'publish\gui',
|
||||
'docs',
|
||||
'scripts\examples'
|
||||
)
|
||||
foreach ($ref in $issRefs) {
|
||||
$abs = Join-Path $repoRoot $ref
|
||||
$exists = Test-Path $abs
|
||||
Write-Host (" {0,-40} exists={1} ({2})" -f $ref, $exists, $abs)
|
||||
}
|
||||
Write-Host ""
|
||||
|
||||
Write-Host "--- runtime context ---" -ForegroundColor Cyan
|
||||
Write-Host " identity: $([Security.Principal.WindowsIdentity]::GetCurrent().Name)"
|
||||
Write-Host " USERPROFILE: $env:USERPROFILE"
|
||||
Write-Host " APPDATA: $env:APPDATA"
|
||||
Write-Host " LOCALAPPDATA: $env:LOCALAPPDATA"
|
||||
Write-Host " TEMP: $env:TEMP"
|
||||
$isccDir = Split-Path $iscc -Parent
|
||||
Write-Host " ISCC dir: $isccDir"
|
||||
foreach ($f in @('ISCC.exe','ISCmplr.dll','ISPP.dll','Default.isl','Compil32.exe')) {
|
||||
$p = Join-Path $isccDir $f
|
||||
Write-Host (" {0,-15} exists={1}" -f $f, (Test-Path $p))
|
||||
}
|
||||
Write-Host ""
|
||||
|
||||
Write-Host " PS location (pre): $((Get-Location).Path)"
|
||||
Write-Host " .NET cwd (pre): $([System.IO.Directory]::GetCurrentDirectory())"
|
||||
|
||||
Push-Location $issDir
|
||||
$savedDotNetCwd = [System.IO.Directory]::GetCurrentDirectory()
|
||||
[System.IO.Directory]::SetCurrentDirectory($issDir)
|
||||
try {
|
||||
Write-Host " PS location (post): $((Get-Location).Path)"
|
||||
Write-Host " .NET cwd (post): $([System.IO.Directory]::GetCurrentDirectory())"
|
||||
|
||||
# Sanity: compile a minimal .iss right next to ours BEFORE attempting the
|
||||
# real one. Minimal has no #defines, no [Code], no [Files], no compression
|
||||
# tweak - just the absolute floor of what ISCC will accept. If THIS fails
|
||||
# under the same SYSTEM context with the same identical exit/error, the
|
||||
# problem is environmental, not in our .iss content.
|
||||
$minIss = Join-Path $issDir "min-test.iss"
|
||||
@"
|
||||
[Setup]
|
||||
AppName=MinTest
|
||||
AppVersion=1.0
|
||||
AppId={{12345678-1234-1234-1234-123456789ABC}
|
||||
DefaultDirName={pf}\MinTest
|
||||
CreateAppDir=no
|
||||
Uninstallable=no
|
||||
OutputBaseFilename=mintest
|
||||
OutputDir=$dist
|
||||
"@ | Set-Content -Path $minIss -Encoding ascii
|
||||
Write-Host ""
|
||||
Write-Host "--- bisect step 1: minimal .iss ---" -ForegroundColor Cyan
|
||||
& $iscc (Split-Path $minIss -Leaf) *>&1 | ForEach-Object { Write-Host " $_" }
|
||||
$minExit = $LASTEXITCODE
|
||||
Write-Host " minimal exit: $minExit"
|
||||
Remove-Item $minIss -ErrorAction SilentlyContinue
|
||||
Write-Host ""
|
||||
|
||||
# Bake the version into a temp .iss and override OutputDir to an absolute
|
||||
# path so nothing in the build depends on cwd resolution.
|
||||
$tempIss = Join-Path $issDir "webhook-server.gen.iss"
|
||||
$issBody = Get-Content $issName -Raw
|
||||
$pattern = '(?s)#ifndef AppVersion\s+#define AppVersion "[^"]*"\s+#endif'
|
||||
if ($issBody -notmatch $pattern) { throw "Could not find #ifndef AppVersion block in $issName" }
|
||||
$issBody = $issBody -replace $pattern, "#define AppVersion `"$version`""
|
||||
Set-Content -Path $tempIss -Value $issBody -Encoding ascii
|
||||
Write-Host " using $tempIss"
|
||||
|
||||
# Capture stdout+stderr together so any error line ISCC emits is visible
|
||||
# in the runner log even if the runner's console capture drops one stream.
|
||||
# /O<absolute> overrides OutputDir so ..\dist isn't resolved relative to
|
||||
# whatever cwd ISCC actually inherits.
|
||||
$logPath = Join-Path $env:TEMP "iscc-$version.log"
|
||||
& $iscc "/O$dist" (Split-Path $tempIss -Leaf) *>&1 | Tee-Object -FilePath $logPath | ForEach-Object { Write-Host $_ }
|
||||
$exit = $LASTEXITCODE
|
||||
Write-Host " ISCC exit code: $exit"
|
||||
Write-Host " ISCC log path: $logPath"
|
||||
if (Test-Path $logPath) {
|
||||
Write-Host " --- iscc log file contents ---"
|
||||
Get-Content $logPath | ForEach-Object { Write-Host " $_" }
|
||||
Write-Host " --- end iscc log ---"
|
||||
}
|
||||
Remove-Item $tempIss -ErrorAction SilentlyContinue
|
||||
} finally {
|
||||
[System.IO.Directory]::SetCurrentDirectory($savedDotNetCwd)
|
||||
Pop-Location
|
||||
}
|
||||
if ($exit -ne 0) { throw "Inno Setup compile failed (exit $exit)" }
|
||||
& $iscc "/DAppVersion=$version" $iss
|
||||
if ($LASTEXITCODE -ne 0) { throw 'Inno Setup compile failed' }
|
||||
|
||||
$out = Get-Item (Join-Path $dist "WebhookServer-Setup-$version.exe")
|
||||
Write-Host ""
|
||||
|
||||
@@ -1,46 +0,0 @@
|
||||
<#
|
||||
.SYNOPSIS
|
||||
Server-side receiver for the env-dump webhook. Reads the JSON body from
|
||||
stdin and writes it to a timestamped file on disk.
|
||||
|
||||
.DESCRIPTION
|
||||
Configure a webhook endpoint like this:
|
||||
Executable: powershell.exe (or pwsh.exe)
|
||||
Arguments: -NoProfile -ExecutionPolicy Bypass -File C:\path\to\save-env-vars.ps1
|
||||
Data passing: [x] Stdin JSON
|
||||
Run As: Service (or any account that can write to $OutDir)
|
||||
|
||||
Output goes to C:\ProgramData\WebhookServer\env-dumps\<host>-<utcstamp>.json
|
||||
by default; override with -OutDir.
|
||||
#>
|
||||
|
||||
[CmdletBinding()]
|
||||
param(
|
||||
[string] $OutDir = 'C:\ProgramData\WebhookServer\env-dumps'
|
||||
)
|
||||
|
||||
$ErrorActionPreference = 'Stop'
|
||||
|
||||
if (-not (Test-Path $OutDir)) {
|
||||
New-Item -ItemType Directory -Path $OutDir -Force | Out-Null
|
||||
}
|
||||
|
||||
$body = [Console]::In.ReadToEnd()
|
||||
if ([string]::IsNullOrWhiteSpace($body)) {
|
||||
Write-Error 'Empty request body on stdin.'
|
||||
exit 2
|
||||
}
|
||||
|
||||
# Parse so we can pull the host name for the filename, and to fail fast on
|
||||
# malformed JSON before writing it.
|
||||
$parsed = $body | ConvertFrom-Json
|
||||
$hostName = if ($parsed.host) { $parsed.host } else { 'unknown' }
|
||||
$safeHost = ($hostName -replace '[^A-Za-z0-9_.-]', '_')
|
||||
$stamp = (Get-Date).ToUniversalTime().ToString('yyyyMMddTHHmmssZ')
|
||||
$path = Join-Path $OutDir "$safeHost-$stamp.json"
|
||||
|
||||
# Persist the original body verbatim - keeps key ordering and avoids any
|
||||
# round-trip surprises from ConvertTo-Json.
|
||||
Set-Content -Path $path -Value $body -Encoding utf8
|
||||
|
||||
Write-Host "Saved $($body.Length) bytes to $path"
|
||||
@@ -1,68 +0,0 @@
|
||||
<#
|
||||
.SYNOPSIS
|
||||
Collects env vars from PowerShell and bash, packages them into a single
|
||||
JSON object, and POSTs the result to a Webhook Server endpoint.
|
||||
|
||||
.DESCRIPTION
|
||||
Output JSON shape:
|
||||
{
|
||||
"host": "<computername>",
|
||||
"capturedAt":"2026-05-08T12:34:56Z",
|
||||
"pwsh": { "VAR": "value", ... },
|
||||
"bash": { "VAR": "value", ... }
|
||||
}
|
||||
|
||||
Pair this with `save-env-vars.ps1` on the server side - configure an
|
||||
endpoint with StdinJson enabled and that script as the executable.
|
||||
#>
|
||||
|
||||
[CmdletBinding()]
|
||||
param(
|
||||
[string] $WebhookUrl = 'http://localhost:8080/hook/env-dump',
|
||||
[string] $Bearer = '',
|
||||
[string] $BashExe = 'bash'
|
||||
)
|
||||
|
||||
$ErrorActionPreference = 'Stop'
|
||||
|
||||
# --- pwsh env vars --------------------------------------------------------
|
||||
$pwshVars = [ordered]@{}
|
||||
Get-ChildItem Env: | Sort-Object Name | ForEach-Object {
|
||||
$pwshVars[$_.Name] = $_.Value
|
||||
}
|
||||
|
||||
# --- bash env vars --------------------------------------------------------
|
||||
$bashVars = [ordered]@{}
|
||||
$bashCmd = Get-Command $BashExe -ErrorAction SilentlyContinue
|
||||
if ($null -ne $bashCmd) {
|
||||
# `env -0` separates entries with NUL so values containing newlines stay intact.
|
||||
$raw = & $bashCmd.Source -c 'env -0' 2>$null
|
||||
if ($LASTEXITCODE -eq 0 -and $raw) {
|
||||
foreach ($entry in ($raw -split "`0")) {
|
||||
if ([string]::IsNullOrEmpty($entry)) { continue }
|
||||
$eq = $entry.IndexOf('=')
|
||||
if ($eq -lt 1) { continue }
|
||||
$bashVars[$entry.Substring(0, $eq)] = $entry.Substring($eq + 1)
|
||||
}
|
||||
}
|
||||
} else {
|
||||
Write-Warning "bash not found on PATH (looked for '$BashExe'); 'bash' section will be empty."
|
||||
}
|
||||
|
||||
# --- assemble payload -----------------------------------------------------
|
||||
$payload = [ordered]@{
|
||||
host = $env:COMPUTERNAME
|
||||
capturedAt = (Get-Date).ToUniversalTime().ToString('o')
|
||||
pwsh = $pwshVars
|
||||
bash = $bashVars
|
||||
}
|
||||
|
||||
$json = $payload | ConvertTo-Json -Depth 5 -Compress
|
||||
|
||||
# --- POST -----------------------------------------------------------------
|
||||
$headers = @{ 'Content-Type' = 'application/json' }
|
||||
if ($Bearer) { $headers['Authorization'] = "Bearer $Bearer" }
|
||||
|
||||
Write-Host "POST $WebhookUrl ($($json.Length) bytes; pwsh=$($pwshVars.Count), bash=$($bashVars.Count))"
|
||||
$response = Invoke-RestMethod -Method Post -Uri $WebhookUrl -Headers $headers -Body $json
|
||||
$response | ConvertTo-Json -Depth 5
|
||||
@@ -1,90 +0,0 @@
|
||||
<#
|
||||
.SYNOPSIS
|
||||
Webhook-server-side receiver: posts a Slack/Teams notification when a VPG
|
||||
fires its pre or post recovery script.
|
||||
|
||||
.DESCRIPTION
|
||||
Reads the JSON body from stdin (the payload sent by zerto-zvma-send.ps1),
|
||||
builds a phase-aware message, and posts it to an Incoming Webhook URL.
|
||||
|
||||
The message highlights:
|
||||
- VPG name + operation type (Test / Failover / Move / ...)
|
||||
- Whether ZertoForce was set (only relevant pre)
|
||||
- VM display names included in the run
|
||||
- Phase (pre vs post) so you can see the bracketing in chat
|
||||
|
||||
Wire up two endpoints:
|
||||
/hook/zerto-pre -> this script with -Phase pre (pass via args)
|
||||
/hook/zerto-post -> this script with -Phase post
|
||||
|
||||
Or one endpoint per phase, each pointing at this script. The script reads
|
||||
`phase` from the JSON body, so the -Phase param is optional.
|
||||
|
||||
.NOTES
|
||||
Compatible with:
|
||||
- Slack Incoming Webhooks (posts {"text": "..."})
|
||||
- Teams legacy connector "Incoming Webhook" (same body shape)
|
||||
- Discord webhooks (use ?wait=true for body, but text is "content" not
|
||||
"text" - tweak below)
|
||||
|
||||
Endpoint config:
|
||||
ExecutorType: WindowsPowerShell or PowerShell 7
|
||||
ScriptPath: C:\scripts\zerto-receiver-notify.ps1
|
||||
DataPassing: [x] Stdin JSON
|
||||
ResponseMode: async (we don't need to block the VPG on a chat post)
|
||||
#>
|
||||
|
||||
[CmdletBinding()]
|
||||
param(
|
||||
[string] $NotifyUrl = $env:NOTIFY_URL # set on the Webhook Server host, or hardcode below
|
||||
)
|
||||
|
||||
$ErrorActionPreference = 'Stop'
|
||||
|
||||
if (-not $NotifyUrl) {
|
||||
# Fall back to a hardcoded URL if NOTIFY_URL env var isn't set.
|
||||
# Replace with your Slack/Teams Incoming Webhook URL.
|
||||
$NotifyUrl = 'https://hooks.slack.com/services/REPLACE/ME/HERE'
|
||||
}
|
||||
|
||||
$body = [Console]::In.ReadToEnd()
|
||||
if ([string]::IsNullOrWhiteSpace($body)) {
|
||||
Write-Error 'Empty stdin - expected JSON body from the webhook server.'
|
||||
exit 2
|
||||
}
|
||||
$p = $body | ConvertFrom-Json
|
||||
|
||||
$z = $p.zerto
|
||||
$phase = if ($p.phase) { $p.phase } else { 'unknown' }
|
||||
$op = if ($z.operation) { $z.operation } else { 'unknown' }
|
||||
|
||||
# Pick an icon based on operation. Test is benign; Failover/Move are real.
|
||||
$icon = switch ($op) {
|
||||
'Test' { ':test_tube:' }
|
||||
'Failover' { ':rotating_light:' }
|
||||
'Move' { ':truck:' }
|
||||
default { ':information_source:' }
|
||||
}
|
||||
|
||||
$forceTag = if ($phase -eq 'pre' -and $z.force -eq 'Yes') { ' *(FORCE)*' } else { '' }
|
||||
|
||||
$lines = @(
|
||||
"$icon *Zerto $op* - phase: ``$phase``$forceTag"
|
||||
"VPG: ``$($z.vpgName)``"
|
||||
"VMs: ``$($z.vmDisplayNames)``"
|
||||
"Hypervisor mgr: ``$($z.hypervisorManagerIP):$($z.hypervisorManagerPort)``"
|
||||
"Captured: $($p.capturedAt) (from $($p.host))"
|
||||
)
|
||||
$text = $lines -join "`n"
|
||||
|
||||
$payload = @{ text = $text } | ConvertTo-Json -Compress
|
||||
|
||||
try {
|
||||
Invoke-RestMethod -Method Post -Uri $NotifyUrl `
|
||||
-ContentType 'application/json' -Body $payload -TimeoutSec 10 | Out-Null
|
||||
Write-Host "[$phase] notified $op for VPG '$($z.vpgName)'"
|
||||
}
|
||||
catch {
|
||||
Write-Error "Notification post failed: $($_.Exception.Message)"
|
||||
exit 1
|
||||
}
|
||||
@@ -1,140 +0,0 @@
|
||||
<#
|
||||
.SYNOPSIS
|
||||
Webhook-server-side receiver: post-failover VM health check. Pings each
|
||||
VM in the VPG and probes a configurable TCP port; writes a per-run
|
||||
report to disk.
|
||||
|
||||
.DESCRIPTION
|
||||
Intended for the POST-recovery webhook only - on a Test or real Failover,
|
||||
once the VMs are powered on at the recovery site, we can spot-check that
|
||||
they responded to ICMP and that a known port is listening (RDP, SSH,
|
||||
HTTP, etc).
|
||||
|
||||
Skips itself entirely on the pre-recovery phase (nothing's running yet)
|
||||
and on $z.operation values that don't bring VMs up.
|
||||
|
||||
Wire up one endpoint:
|
||||
/hook/zerto-post -> this script
|
||||
DataPassing: [x] Stdin JSON
|
||||
ResponseMode: async
|
||||
|
||||
.NOTES
|
||||
VmDisplayNames is a comma-separated list for multi-VM VPGs; some Zerto
|
||||
versions wrap each name in parentheses (e.g. "vm1(1)(1)(1)") to disambig
|
||||
after Test failover. We strip the trailing parenthesised suffixes when
|
||||
resolving DNS so the recovered hostname is what we ping.
|
||||
|
||||
Endpoint config:
|
||||
ExecutorType: WindowsPowerShell or PowerShell 7
|
||||
ScriptPath: C:\scripts\zerto-receiver-vm-healthcheck.ps1
|
||||
DataPassing: [x] Stdin JSON
|
||||
ResponseMode: async
|
||||
TimeoutSeconds: 120 (this script does network I/O - bump from default)
|
||||
#>
|
||||
|
||||
[CmdletBinding()]
|
||||
param(
|
||||
[int] $ProbePort = 3389, # RDP. Use 22 for Linux, 80/443 for web tier.
|
||||
[int] $PingTimeout = 2000, # ms
|
||||
[string] $ReportDir = 'C:\ProgramData\WebhookServer\zerto-healthchecks'
|
||||
)
|
||||
|
||||
$ErrorActionPreference = 'Stop'
|
||||
|
||||
# --- read + parse payload -------------------------------------------------
|
||||
$body = [Console]::In.ReadToEnd()
|
||||
if ([string]::IsNullOrWhiteSpace($body)) {
|
||||
Write-Error 'Empty stdin.'
|
||||
exit 2
|
||||
}
|
||||
$p = $body | ConvertFrom-Json
|
||||
|
||||
$z = $p.zerto
|
||||
$phase = $p.phase
|
||||
$op = $z.operation
|
||||
|
||||
# Skip if this isn't a post-phase run for an op that powers VMs on.
|
||||
if ($phase -ne 'post') {
|
||||
Write-Host "Phase '$phase' - nothing to check yet, skipping."
|
||||
exit 0
|
||||
}
|
||||
if ($op -notin @('Test','Failover','Move','FailoverBeforeCommit','FailoverDuringCommit')) {
|
||||
Write-Host "Operation '$op' doesn't bring VMs up; skipping."
|
||||
exit 0
|
||||
}
|
||||
|
||||
# --- parse VM list --------------------------------------------------------
|
||||
function Strip-ZertoSuffix {
|
||||
param([string] $name)
|
||||
# "ubuntu-2404(1)(1)(1)" -> "ubuntu-2404"
|
||||
return ($name -replace '(\([^)]*\))+\s*$','').Trim()
|
||||
}
|
||||
|
||||
$rawNames = ($z.vmDisplayNames -split '[,;]') | ForEach-Object { $_.Trim() } |
|
||||
Where-Object { $_ }
|
||||
if (-not $rawNames) {
|
||||
Write-Warning 'No VM display names in payload - nothing to check.'
|
||||
exit 0
|
||||
}
|
||||
|
||||
# --- run checks -----------------------------------------------------------
|
||||
$results = foreach ($raw in $rawNames) {
|
||||
$clean = Strip-ZertoSuffix $raw
|
||||
$pingOk = $false
|
||||
$portOk = $false
|
||||
$err = $null
|
||||
|
||||
try {
|
||||
$pingOk = (Test-Connection -ComputerName $clean -Count 1 -Quiet `
|
||||
-TimeoutSeconds ([math]::Max(1, [int]($PingTimeout / 1000))) `
|
||||
-ErrorAction Stop)
|
||||
} catch { $err = "ping: $($_.Exception.Message)" }
|
||||
|
||||
try {
|
||||
$portOk = (Test-NetConnection -ComputerName $clean -Port $ProbePort `
|
||||
-InformationLevel Quiet -WarningAction SilentlyContinue)
|
||||
} catch { $err = ($err, "port: $($_.Exception.Message)") -ne $null -join '; ' }
|
||||
|
||||
[pscustomobject]@{
|
||||
DisplayName = $raw
|
||||
Resolved = $clean
|
||||
PingOk = $pingOk
|
||||
PortOk = $portOk
|
||||
ProbePort = $ProbePort
|
||||
Error = $err
|
||||
}
|
||||
}
|
||||
|
||||
# --- write report ---------------------------------------------------------
|
||||
if (-not (Test-Path $ReportDir)) {
|
||||
New-Item -ItemType Directory -Path $ReportDir -Force | Out-Null
|
||||
}
|
||||
|
||||
$safeVpg = ($z.vpgName -replace '[^A-Za-z0-9_.-]','_')
|
||||
$stamp = (Get-Date).ToUniversalTime().ToString('yyyyMMddTHHmmssZ')
|
||||
$file = Join-Path $ReportDir "$safeVpg-$op-$stamp.json"
|
||||
|
||||
$report = [ordered]@{
|
||||
vpgName = $z.vpgName
|
||||
operation = $op
|
||||
phase = $phase
|
||||
capturedAt = $p.capturedAt
|
||||
completedAt = (Get-Date).ToUniversalTime().ToString('o')
|
||||
probePort = $ProbePort
|
||||
vms = $results
|
||||
summary = @{
|
||||
total = $results.Count
|
||||
pingFailures = ($results | Where-Object { -not $_.PingOk }).Count
|
||||
portFailures = ($results | Where-Object { -not $_.PortOk }).Count
|
||||
}
|
||||
}
|
||||
$report | ConvertTo-Json -Depth 5 | Set-Content -Path $file -Encoding utf8
|
||||
|
||||
# Console output goes back via the webhook callback (if configured) so the
|
||||
# Zerto-side script log shows a quick summary even though the call is async.
|
||||
$bad = $report.summary.pingFailures + $report.summary.portFailures
|
||||
Write-Host "[$op/$phase] $($z.vpgName): $($results.Count) VM(s), $bad issue(s). Report: $file"
|
||||
|
||||
# Exit non-zero if anything failed, so the webhook server's failOnNonZeroExit
|
||||
# turns this into a 502 for the caller (and shows up in the run history).
|
||||
if ($bad -gt 0) { exit 1 }
|
||||
@@ -1,74 +0,0 @@
|
||||
<#
|
||||
.SYNOPSIS
|
||||
Zerto pre/post script (ZVMA / Linux scripts-service edition). Reads the
|
||||
Zerto-injected environment variables and POSTs them to a Webhook Server
|
||||
endpoint as a structured JSON payload.
|
||||
|
||||
.DESCRIPTION
|
||||
Drop into a VPG's Recovery Scripts in the ZVM UI:
|
||||
VPG settings -> Recovery -> Scripts -> Pre / Post Recovery Script
|
||||
Path: /app/scripts-files/zerto-zvma-send.ps1
|
||||
Parameters: -Phase pre (or -Phase post on the post-recovery slot)
|
||||
|
||||
Configure $WebhookUrl + $Bearer (or use the -WebhookUrl / -Bearer params
|
||||
so one script file can serve multiple VPGs / endpoints).
|
||||
|
||||
Async by default - the call returns 202 in milliseconds and the actual
|
||||
work runs in the webhook server's background, so the VPG sequence is
|
||||
never blocked by slow downstream actions (DNS, notifications, etc.).
|
||||
|
||||
.NOTES
|
||||
The scripts-service container has pwsh 7 and curl available. This script
|
||||
uses Invoke-RestMethod to keep things native to PowerShell.
|
||||
#>
|
||||
|
||||
[CmdletBinding()]
|
||||
param(
|
||||
[Parameter(Mandatory)]
|
||||
[ValidateSet('pre', 'post')]
|
||||
[string] $Phase,
|
||||
|
||||
[string] $WebhookUrl = 'http://192.168.50.250:8080/hook/zerto-{phase}',
|
||||
[string] $Bearer = '',
|
||||
[int] $TimeoutSec = 10
|
||||
)
|
||||
|
||||
$ErrorActionPreference = 'Stop'
|
||||
|
||||
# Resolve {phase} placeholder so one URL template can route to /hook/zerto-pre
|
||||
# and /hook/zerto-post. Plain URLs without the token work too.
|
||||
$url = $WebhookUrl.Replace('{phase}', $Phase)
|
||||
|
||||
$payload = [ordered]@{
|
||||
phase = $Phase
|
||||
capturedAt = (Get-Date).ToUniversalTime().ToString('o')
|
||||
host = $env:HOSTNAME # scripts-service pod name
|
||||
zerto = [ordered]@{
|
||||
vpgName = $env:ZertoVPGName
|
||||
internalVpgName = $env:ZertoInternalVpgName
|
||||
operation = $env:ZertoOperation # Test / Failover / Move / ...
|
||||
force = $env:ZertoForce # only meaningful pre
|
||||
vmDisplayNames = $env:VmDisplayNames # comma-separated for multi-VM VPGs
|
||||
hypervisorManagerIP = $env:ZertoHypervisorManagerIP
|
||||
hypervisorManagerPort = $env:ZertoHypervisorManagerPort
|
||||
outputDir = $env:ZertoOutputDir
|
||||
workingDir = $env:ZertoWorkingDir
|
||||
}
|
||||
}
|
||||
|
||||
$body = $payload | ConvertTo-Json -Depth 4 -Compress
|
||||
|
||||
$headers = @{ 'Content-Type' = 'application/json' }
|
||||
if ($Bearer) { $headers['Authorization'] = "Bearer $Bearer" }
|
||||
|
||||
try {
|
||||
$resp = Invoke-RestMethod -Method Post -Uri $url -Headers $headers `
|
||||
-Body $body -TimeoutSec $TimeoutSec
|
||||
Write-Host "[$Phase] webhook accepted: $($resp | ConvertTo-Json -Compress)"
|
||||
}
|
||||
catch {
|
||||
# Pre/post failures should not block the VPG operation. Log loudly and exit 0
|
||||
# so Zerto's recovery sequence continues. Flip to `exit 1` if you want a
|
||||
# webhook outage to fail the failover.
|
||||
Write-Warning "[$Phase] webhook call failed: $($_.Exception.Message)"
|
||||
}
|
||||
@@ -1,159 +0,0 @@
|
||||
<#
|
||||
.SYNOPSIS
|
||||
Mirrors the in-repo docs/ folder to a GitHub or Gitea wiki repo.
|
||||
|
||||
.DESCRIPTION
|
||||
Wikis are separate git repositories (e.g. <repo>.wiki.git) with a flat URL
|
||||
structure. This script:
|
||||
|
||||
1. Clones the wiki repo into a temp directory.
|
||||
2. Wipes its existing .md content.
|
||||
3. Copies each docs/*.md to a flattened wiki-style page name.
|
||||
4. Rewrites in-repo markdown links so they point at the wiki page slugs.
|
||||
5. Generates a _Sidebar.md so every wiki page has a navigation sidebar.
|
||||
6. Commits and pushes back if anything changed.
|
||||
|
||||
Idempotent. Safe to re-run.
|
||||
|
||||
.PARAMETER WikiUrl
|
||||
Full HTTPS URL to the wiki repo, including any embedded credentials. Examples:
|
||||
https://github.com/recklessop/webhook-server.wiki.git
|
||||
https://x-access-token:$TOKEN@github.com/recklessop/webhook-server.wiki.git
|
||||
https://justin:$GITEA_TOKEN@git.jpaul.io/justin/webhook-server.wiki.git
|
||||
|
||||
.PARAMETER AuthorName
|
||||
git committer name. Defaults to "Webhook Server Wiki Sync".
|
||||
|
||||
.PARAMETER AuthorEmail
|
||||
git committer email. Defaults to "noreply@jpaul.me".
|
||||
|
||||
.EXAMPLE
|
||||
# Manual sync to Gitea (token in env)
|
||||
$env:GITEA_TOKEN = '...'
|
||||
./scripts/sync-wiki.ps1 -WikiUrl "https://justin:$env:GITEA_TOKEN@git.jpaul.io/justin/webhook-server.wiki.git"
|
||||
|
||||
.EXAMPLE
|
||||
# Manual sync to GitHub (gh-issued token)
|
||||
$token = & gh auth token
|
||||
./scripts/sync-wiki.ps1 -WikiUrl "https://x-access-token:$token@github.com/recklessop/webhook-server.wiki.git"
|
||||
#>
|
||||
[CmdletBinding()]
|
||||
param(
|
||||
[Parameter(Mandatory)][string]$WikiUrl,
|
||||
[string]$AuthorName = 'Webhook Server Wiki Sync',
|
||||
[string]$AuthorEmail = 'noreply@jpaul.me'
|
||||
)
|
||||
|
||||
# Continue (not Stop) because git writes informational messages to stderr
|
||||
# (CRLF warnings, "remote: Processed N references" etc.) which PowerShell 5.1
|
||||
# escalates to a script-fatal error under Stop. We check $LASTEXITCODE
|
||||
# manually after each git call instead.
|
||||
$ErrorActionPreference = 'Continue'
|
||||
|
||||
$repoRoot = Split-Path -Parent $PSScriptRoot
|
||||
$docsDir = Join-Path $repoRoot 'docs'
|
||||
$workDir = Join-Path $env:TEMP ("webhook-wiki-{0}" -f ([guid]::NewGuid().ToString('N').Substring(0, 8)))
|
||||
|
||||
# Source path (relative to docs/) -> wiki page slug. Order matters for the sidebar.
|
||||
$mapping = [ordered]@{}
|
||||
$mapping.Add('README.md', 'Home')
|
||||
$mapping.Add('concepts.md', 'Concepts')
|
||||
$mapping.Add('installation.md', 'Installation')
|
||||
$mapping.Add('upgrading.md', 'Upgrading')
|
||||
$mapping.Add('uninstalling.md', 'Uninstalling')
|
||||
$mapping.Add('runas-modes.md', 'Run-As-Modes')
|
||||
$mapping.Add('service-account-and-ad.md', 'Service-Account-and-AD')
|
||||
$mapping.Add('network-and-security.md', 'Network-and-Security')
|
||||
$mapping.Add('troubleshooting.md', 'Troubleshooting')
|
||||
$mapping.Add('recipes/zerto-zvma-pre-post.md', 'Recipe-Zerto-ZVMA')
|
||||
$mapping.Add('recipes/github-style-hmac.md', 'Recipe-GitHub-HMAC')
|
||||
$mapping.Add('recipes/ui-on-desktop.md', 'Recipe-UI-on-Desktop')
|
||||
|
||||
function Rewrite-Links([string]$content) {
|
||||
foreach ($m in $mapping.GetEnumerator()) {
|
||||
# Match (path/to/file.md) and (path/to/file.md#anchor) inside markdown
|
||||
# link parens. The lookbehind ensures we're consuming a real link target.
|
||||
$escaped = [regex]::Escape($m.Key)
|
||||
$content = [regex]::Replace($content,
|
||||
"\(\.?\.?/?$escaped(\#[^)\s]*)?\)",
|
||||
"($($m.Value)`$1)")
|
||||
}
|
||||
# Also clean up doubled prefixes like "../../docs/" or "../" pointers that
|
||||
# sometimes appear in cross-folder relative links from docs/recipes/.
|
||||
return $content
|
||||
}
|
||||
|
||||
function New-Sidebar() {
|
||||
$lines = @()
|
||||
$lines += "[Home](Home)"
|
||||
$lines += ""
|
||||
$lines += "## Topical"
|
||||
foreach ($key in @('concepts.md','installation.md','upgrading.md','uninstalling.md','runas-modes.md','service-account-and-ad.md','network-and-security.md','troubleshooting.md')) {
|
||||
$slug = $mapping[$key]
|
||||
$lines += "- [$($slug -replace '-', ' ')]($slug)"
|
||||
}
|
||||
$lines += ""
|
||||
$lines += "## Recipes"
|
||||
foreach ($key in @('recipes/zerto-zvma-pre-post.md','recipes/github-style-hmac.md','recipes/ui-on-desktop.md')) {
|
||||
$slug = $mapping[$key]
|
||||
$lines += "- [$($slug -replace '^Recipe-' -replace '-', ' ')]($slug)"
|
||||
}
|
||||
return ($lines -join "`n")
|
||||
}
|
||||
|
||||
# 1. Clone the wiki.
|
||||
Write-Host "Cloning wiki to $workDir..."
|
||||
& git clone --quiet $WikiUrl $workDir 2>&1 | Out-Null
|
||||
if ($LASTEXITCODE -ne 0) {
|
||||
throw "git clone failed. Has the wiki been initialized? Visit the repo's Wiki tab and create the first page via the UI before running this script."
|
||||
}
|
||||
# Suppress git's CRLF nags for this throwaway clone so they don't become
|
||||
# "errors" via PowerShell's native-command stderr handling.
|
||||
& git -C $workDir config core.autocrlf false 2>&1 | Out-Null
|
||||
& git -C $workDir config core.safecrlf false 2>&1 | Out-Null
|
||||
|
||||
try {
|
||||
Push-Location $workDir
|
||||
try {
|
||||
# 2. Wipe existing markdown so removed source files vanish from the wiki.
|
||||
Get-ChildItem -Filter "*.md" -Force | Remove-Item -Force
|
||||
|
||||
# 3. Copy + transform each source file.
|
||||
$written = 0
|
||||
foreach ($entry in $mapping.GetEnumerator()) {
|
||||
$src = Join-Path $docsDir $entry.Key
|
||||
$dst = Join-Path $workDir "$($entry.Value).md"
|
||||
if (-not (Test-Path $src)) {
|
||||
Write-Warning "Source missing, skipping: $src"
|
||||
continue
|
||||
}
|
||||
$content = Get-Content -LiteralPath $src -Raw
|
||||
$content = Rewrite-Links $content
|
||||
Set-Content -LiteralPath $dst -Value $content -Encoding utf8 -NoNewline
|
||||
$written++
|
||||
}
|
||||
Write-Host "Wrote $written markdown pages."
|
||||
|
||||
# 4. Sidebar
|
||||
Set-Content -LiteralPath (Join-Path $workDir '_Sidebar.md') -Value (New-Sidebar) -Encoding utf8 -NoNewline
|
||||
|
||||
# 5. Commit + push if anything actually changed. Drain stderr from each
|
||||
# git invocation so PowerShell doesn't treat warnings as errors.
|
||||
& git add -A 2>&1 | Out-Null
|
||||
$changes = & git status --porcelain 2>&1
|
||||
if (-not $changes) {
|
||||
Write-Host "Wiki already up to date."
|
||||
return
|
||||
}
|
||||
$sha = & git -C $repoRoot rev-parse --short HEAD 2>&1
|
||||
& git -c "user.name=$AuthorName" -c "user.email=$AuthorEmail" commit -q -m "Sync from docs/ at $sha" 2>&1 | Out-Null
|
||||
if ($LASTEXITCODE -ne 0) { throw "git commit failed (exit $LASTEXITCODE)" }
|
||||
& git push --quiet 2>&1 | Out-Null
|
||||
if ($LASTEXITCODE -ne 0) { throw "git push failed (exit $LASTEXITCODE)" }
|
||||
Write-Host "Pushed updated wiki."
|
||||
}
|
||||
finally { Pop-Location }
|
||||
}
|
||||
finally {
|
||||
Remove-Item -Recurse -Force $workDir -ErrorAction SilentlyContinue
|
||||
}
|
||||
@@ -26,7 +26,6 @@ public static class AdminOps
|
||||
public const string ListBackups = "list-backups";
|
||||
public const string RestoreBackup = "restore-backup";
|
||||
public const string ImportConfig = "import-config";
|
||||
public const string CreateCheckpoint = "create-checkpoint";
|
||||
}
|
||||
|
||||
public sealed class BackupEntry
|
||||
@@ -34,7 +33,6 @@ public sealed class BackupEntry
|
||||
public string FileName { get; set; } = "";
|
||||
public DateTimeOffset SavedAt { get; set; }
|
||||
public long SizeBytes { get; set; }
|
||||
public string? Description { get; set; }
|
||||
}
|
||||
|
||||
public sealed class RestoreBackupArgs
|
||||
@@ -42,11 +40,6 @@ public sealed class RestoreBackupArgs
|
||||
public string FileName { get; set; } = "";
|
||||
}
|
||||
|
||||
public sealed class CreateCheckpointArgs
|
||||
{
|
||||
public string? Description { get; set; }
|
||||
}
|
||||
|
||||
public sealed class AdminRequest
|
||||
{
|
||||
[JsonPropertyName("op")] public string Op { get; set; } = "";
|
||||
|
||||
@@ -48,15 +48,8 @@ public sealed class ConfigStore
|
||||
Directory.CreateDirectory(backupsDir);
|
||||
var stamp = DateTime.UtcNow.ToString("yyyyMMdd-HHmmss");
|
||||
var backupPath = System.IO.Path.Combine(backupsDir, $"config-{stamp}.json");
|
||||
if (!File.Exists(backupPath))
|
||||
{
|
||||
File.Copy(Path, backupPath, overwrite: false);
|
||||
var sidecar = new { description = "Before save", reason = "before-save" };
|
||||
File.WriteAllText(
|
||||
System.IO.Path.ChangeExtension(backupPath, ".meta.json"),
|
||||
JsonSerializer.Serialize(sidecar, ConfigJson.Compact));
|
||||
}
|
||||
PruneBackups(backupsDir, retain: 90);
|
||||
File.Copy(Path, backupPath, overwrite: false);
|
||||
PruneBackups(backupsDir, retain: 30);
|
||||
}
|
||||
catch
|
||||
{
|
||||
@@ -78,18 +71,11 @@ public sealed class ConfigStore
|
||||
private static void PruneBackups(string backupsDir, int retain)
|
||||
{
|
||||
var stale = new DirectoryInfo(backupsDir).GetFiles("config-*.json")
|
||||
.Where(f => !f.Name.EndsWith(".meta.json", StringComparison.OrdinalIgnoreCase))
|
||||
.OrderByDescending(f => f.Name)
|
||||
.Skip(retain);
|
||||
foreach (var f in stale)
|
||||
{
|
||||
try
|
||||
{
|
||||
f.Delete();
|
||||
var sidecar = System.IO.Path.ChangeExtension(f.FullName, ".meta.json");
|
||||
if (File.Exists(sidecar)) File.Delete(sidecar);
|
||||
}
|
||||
catch { }
|
||||
try { f.Delete(); } catch { }
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@@ -29,12 +29,25 @@
|
||||
<Separator/>
|
||||
<MenuItem Header="_Import config…" Command="{Binding ImportConfigCommand}"/>
|
||||
<MenuItem Header="_Export config…" Command="{Binding ExportConfigCommand}"/>
|
||||
<MenuItem Header="Config _Checkpoints…" Command="{Binding ShowConfigCheckpointsCommand}"/>
|
||||
<Separator/>
|
||||
<MenuItem Header="_Minimize to tray"
|
||||
IsCheckable="True"
|
||||
IsChecked="{Binding MinimizeToTrayEnabled, Mode=TwoWay}"
|
||||
ToolTip="When ticked, closing or minimizing the window hides it to the tray and keeps the GUI process alive. Untick to make the X button quit the app."/>
|
||||
<MenuItem Header="Config _Checkpoints"
|
||||
ItemsSource="{Binding Backups}"
|
||||
ToolTip="Snapshots taken automatically before each save. Click one to restore."
|
||||
SubmenuOpened="OnBackupsSubmenuOpened">
|
||||
<MenuItem.ItemContainerStyle>
|
||||
<Style TargetType="MenuItem">
|
||||
<Setter Property="Header">
|
||||
<Setter.Value>
|
||||
<MultiBinding StringFormat="{}{0:yyyy-MM-dd HH:mm:ss} ({1:n0} bytes)">
|
||||
<Binding Path="SavedAt"/>
|
||||
<Binding Path="SizeBytes"/>
|
||||
</MultiBinding>
|
||||
</Setter.Value>
|
||||
</Setter>
|
||||
<Setter Property="Command" Value="{Binding DataContext.RestoreBackupCommand, RelativeSource={RelativeSource AncestorType=Window}}"/>
|
||||
<Setter Property="CommandParameter" Value="{Binding}"/>
|
||||
</Style>
|
||||
</MenuItem.ItemContainerStyle>
|
||||
</MenuItem>
|
||||
<Separator/>
|
||||
<MenuItem Header="E_xit" Command="{Binding ExitCommand}"/>
|
||||
</MenuItem>
|
||||
@@ -44,8 +57,6 @@
|
||||
<MenuItem Header="_Restart service" Command="{Binding RestartServiceCommand}"/>
|
||||
</MenuItem>
|
||||
<MenuItem Header="_Help">
|
||||
<MenuItem Header="_Documentation…" Command="{Binding OpenDocumentationCommand}"/>
|
||||
<Separator/>
|
||||
<MenuItem Header="_About Webhook Server…" Command="{Binding ShowAboutCommand}"/>
|
||||
</MenuItem>
|
||||
</Menu>
|
||||
@@ -68,26 +79,17 @@
|
||||
<DataGrid.RowStyle>
|
||||
<Style TargetType="DataGridRow">
|
||||
<EventSetter Event="MouseDoubleClick" Handler="OnRowDoubleClick"/>
|
||||
<!-- The ContextMenu lives in its own visual tree (a popup), so
|
||||
AncestorType=Window doesn't resolve from inside menu items.
|
||||
Stash MainViewModel on the row's Tag here (still in the
|
||||
Window's tree), then reach it from the menu via
|
||||
PlacementTarget.Tag. -->
|
||||
<Setter Property="Tag" Value="{Binding DataContext, RelativeSource={RelativeSource AncestorType=Window}}"/>
|
||||
<Setter Property="ContextMenu">
|
||||
<Setter.Value>
|
||||
<ContextMenu>
|
||||
<MenuItem Header="_Edit…"
|
||||
Command="{Binding PlacementTarget.Tag.EditEndpointCommand, RelativeSource={RelativeSource AncestorType=ContextMenu}}"/>
|
||||
<MenuItem Header="_Copy URL"
|
||||
Command="{Binding PlacementTarget.Tag.CopyEndpointUrlCommand, RelativeSource={RelativeSource AncestorType=ContextMenu}}"/>
|
||||
<MenuItem Header="_Edit…" Command="{Binding DataContext.EditEndpointCommand, RelativeSource={RelativeSource AncestorType=Window}}"/>
|
||||
<MenuItem Header="_Copy URL" Command="{Binding DataContext.CopyEndpointUrlCommand, RelativeSource={RelativeSource AncestorType=Window}}"/>
|
||||
<Separator/>
|
||||
<MenuItem Header="Toggle _enabled"
|
||||
Command="{Binding PlacementTarget.Tag.ToggleEnabledCommand, RelativeSource={RelativeSource AncestorType=ContextMenu}}"
|
||||
CommandParameter="{Binding PlacementTarget.DataContext, RelativeSource={RelativeSource AncestorType=ContextMenu}}"/>
|
||||
Command="{Binding DataContext.ToggleEnabledCommand, RelativeSource={RelativeSource AncestorType=Window}}"
|
||||
CommandParameter="{Binding}"/>
|
||||
<Separator/>
|
||||
<MenuItem Header="_Delete…"
|
||||
Command="{Binding PlacementTarget.Tag.DeleteEndpointCommand, RelativeSource={RelativeSource AncestorType=ContextMenu}}"/>
|
||||
<MenuItem Header="_Delete…" Command="{Binding DataContext.DeleteEndpointCommand, RelativeSource={RelativeSource AncestorType=Window}}"/>
|
||||
</ContextMenu>
|
||||
</Setter.Value>
|
||||
</Setter>
|
||||
|
||||
@@ -1,4 +1,3 @@
|
||||
using System.ComponentModel;
|
||||
using System.Windows;
|
||||
using System.Windows.Controls;
|
||||
using System.Windows.Input;
|
||||
@@ -12,56 +11,26 @@ public partial class MainWindow : Window
|
||||
private readonly TrayIcon _tray;
|
||||
private readonly MainViewModel _vm;
|
||||
|
||||
/// <summary>
|
||||
/// Set to true when the user has explicitly asked to quit (File -> Exit or
|
||||
/// Tray -> Exit). The OnClosing handler reads this to decide whether to
|
||||
/// actually let the window close or hide it to the tray.
|
||||
/// </summary>
|
||||
public bool ExitForReal { get; set; }
|
||||
|
||||
public MainWindow()
|
||||
{
|
||||
InitializeComponent();
|
||||
_vm = new MainViewModel(new AdminPipeClient());
|
||||
DataContext = _vm;
|
||||
_vm.RealExitRequested += OnRealExitRequested;
|
||||
|
||||
_tray = new TrayIcon(
|
||||
resolveMainWindow: () => Application.Current.MainWindow,
|
||||
restartServiceAsync: async () => await new AdminPipeClient().RestartListenerAsync(),
|
||||
onExit: OnRealExitRequested);
|
||||
restartServiceAsync: async () => await new AdminPipeClient().RestartListenerAsync());
|
||||
|
||||
Loaded += async (_, _) => await _vm.RefreshCommand.ExecuteAsync(null);
|
||||
StateChanged += OnStateChanged;
|
||||
Closing += OnClosing;
|
||||
}
|
||||
|
||||
private void OnClosing(object? sender, CancelEventArgs e)
|
||||
{
|
||||
if (ExitForReal || !_vm.MinimizeToTrayEnabled)
|
||||
{
|
||||
_tray.Dispose();
|
||||
return;
|
||||
}
|
||||
// Treat the X button / Alt+F4 like a minimize: hide to tray, keep the
|
||||
// process alive so the tray icon persists.
|
||||
e.Cancel = true;
|
||||
Hide();
|
||||
ShowInTaskbar = false;
|
||||
}
|
||||
|
||||
private void OnRealExitRequested()
|
||||
{
|
||||
ExitForReal = true;
|
||||
Application.Current.Shutdown();
|
||||
Closed += (_, _) => _tray.Dispose();
|
||||
}
|
||||
|
||||
private void OnStateChanged(object? sender, EventArgs e)
|
||||
{
|
||||
// Minimize-to-tray: hide the window when the user minimizes IF they've
|
||||
// opted in via File -> Minimize to tray. Otherwise behave like a normal
|
||||
// Windows minimize.
|
||||
if (WindowState == WindowState.Minimized && _vm.MinimizeToTrayEnabled)
|
||||
// Minimize-to-tray: hide the window when the user minimizes; restoring is
|
||||
// via the tray icon's double-click or context menu.
|
||||
if (WindowState == WindowState.Minimized)
|
||||
{
|
||||
Hide();
|
||||
ShowInTaskbar = false;
|
||||
@@ -84,4 +53,9 @@ public partial class MainWindow : Window
|
||||
vm.EditEndpointCommand.Execute(null);
|
||||
}
|
||||
|
||||
private async void OnBackupsSubmenuOpened(object sender, RoutedEventArgs e)
|
||||
{
|
||||
if (DataContext is MainViewModel vm)
|
||||
await vm.RefreshBackupsCommand.ExecuteAsync(null);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -100,7 +100,4 @@ public sealed class AdminPipeClient
|
||||
|
||||
public Task<AdminResponse> ImportConfigAsync(ServerConfig config, CancellationToken ct = default) =>
|
||||
InvokeAsync(AdminOps.ImportConfig, config, ct);
|
||||
|
||||
public Task<BackupEntry?> CreateCheckpointAsync(string? description, CancellationToken ct = default) =>
|
||||
InvokeAsync<BackupEntry>(AdminOps.CreateCheckpoint, new CreateCheckpointArgs { Description = description }, ct);
|
||||
}
|
||||
|
||||
@@ -1,50 +0,0 @@
|
||||
using System.IO;
|
||||
using System.Text.Json;
|
||||
|
||||
namespace WebhookServer.Gui.Services;
|
||||
|
||||
/// <summary>
|
||||
/// Per-user GUI preferences that don't belong in the service-side ServerConfig.
|
||||
/// Persisted to %APPDATA%\WebhookServer\gui.json. Best-effort: failures to read
|
||||
/// or write fall back silently to defaults.
|
||||
/// </summary>
|
||||
public sealed class GuiSettings
|
||||
{
|
||||
/// <summary>
|
||||
/// When true, the X / Alt+F4 / minimize buttons hide the window to the tray
|
||||
/// and keep the GUI process alive. When false, X exits the app and minimize
|
||||
/// behaves like a normal Windows minimize.
|
||||
/// </summary>
|
||||
public bool MinimizeToTrayEnabled { get; set; } = true;
|
||||
|
||||
private static string FilePath => Path.Combine(
|
||||
Environment.GetFolderPath(Environment.SpecialFolder.ApplicationData),
|
||||
"WebhookServer",
|
||||
"gui.json");
|
||||
|
||||
public static GuiSettings Load()
|
||||
{
|
||||
try
|
||||
{
|
||||
if (File.Exists(FilePath))
|
||||
{
|
||||
var json = File.ReadAllText(FilePath);
|
||||
if (!string.IsNullOrWhiteSpace(json))
|
||||
return JsonSerializer.Deserialize<GuiSettings>(json) ?? new GuiSettings();
|
||||
}
|
||||
}
|
||||
catch { /* fall through to defaults */ }
|
||||
return new GuiSettings();
|
||||
}
|
||||
|
||||
public void Save()
|
||||
{
|
||||
try
|
||||
{
|
||||
var dir = Path.GetDirectoryName(FilePath);
|
||||
if (!string.IsNullOrEmpty(dir)) Directory.CreateDirectory(dir);
|
||||
File.WriteAllText(FilePath, JsonSerializer.Serialize(this, new JsonSerializerOptions { WriteIndented = true }));
|
||||
}
|
||||
catch { /* best effort */ }
|
||||
}
|
||||
}
|
||||
@@ -16,13 +16,11 @@ public sealed class TrayIcon : IDisposable
|
||||
private readonly NotifyIcon _icon;
|
||||
private readonly Func<Window?> _resolveMainWindow;
|
||||
private readonly Func<Task> _restartServiceAsync;
|
||||
private readonly Action _onExit;
|
||||
|
||||
public TrayIcon(Func<Window?> resolveMainWindow, Func<Task> restartServiceAsync, Action onExit)
|
||||
public TrayIcon(Func<Window?> resolveMainWindow, Func<Task> restartServiceAsync)
|
||||
{
|
||||
_resolveMainWindow = resolveMainWindow;
|
||||
_restartServiceAsync = restartServiceAsync;
|
||||
_onExit = onExit;
|
||||
|
||||
_icon = new NotifyIcon
|
||||
{
|
||||
@@ -41,7 +39,7 @@ public sealed class TrayIcon : IDisposable
|
||||
menu.Items.Add(new ToolStripSeparator());
|
||||
menu.Items.Add("&Restart service", null, async (_, _) => await _restartServiceAsync().ConfigureAwait(false));
|
||||
menu.Items.Add(new ToolStripSeparator());
|
||||
menu.Items.Add("E&xit", null, (_, _) => _onExit());
|
||||
menu.Items.Add("E&xit", null, (_, _) => Application.Current.Shutdown());
|
||||
return menu;
|
||||
}
|
||||
|
||||
|
||||
@@ -1,111 +0,0 @@
|
||||
using System.Collections.ObjectModel;
|
||||
using System.Runtime.Versioning;
|
||||
using CommunityToolkit.Mvvm.ComponentModel;
|
||||
using CommunityToolkit.Mvvm.Input;
|
||||
using WebhookServer.Core.Ipc;
|
||||
using WebhookServer.Gui.Services;
|
||||
|
||||
namespace WebhookServer.Gui.ViewModels;
|
||||
|
||||
[SupportedOSPlatform("windows")]
|
||||
public sealed partial class ConfigCheckpointsViewModel : ObservableObject
|
||||
{
|
||||
private readonly AdminPipeClient _client;
|
||||
|
||||
public ObservableCollection<BackupEntry> Checkpoints { get; } = new();
|
||||
|
||||
[ObservableProperty] private BackupEntry? _selected;
|
||||
[ObservableProperty] private string _statusMessage = "";
|
||||
|
||||
public ConfigCheckpointsViewModel(AdminPipeClient client)
|
||||
{
|
||||
_client = client;
|
||||
}
|
||||
|
||||
[RelayCommand]
|
||||
public async Task RefreshAsync()
|
||||
{
|
||||
try
|
||||
{
|
||||
var list = await _client.ListBackupsAsync().ConfigureAwait(false);
|
||||
Application.Current.Dispatcher.Invoke(() =>
|
||||
{
|
||||
Checkpoints.Clear();
|
||||
foreach (var b in list) Checkpoints.Add(b);
|
||||
StatusMessage = list.Count == 0
|
||||
? "No checkpoints yet. Save the config or click Take Checkpoint Now."
|
||||
: $"{list.Count} checkpoint{(list.Count == 1 ? "" : "s")}.";
|
||||
});
|
||||
}
|
||||
catch (Exception ex)
|
||||
{
|
||||
Application.Current.Dispatcher.Invoke(() => StatusMessage = $"Could not load: {ex.Message}");
|
||||
}
|
||||
}
|
||||
|
||||
[RelayCommand]
|
||||
private async Task TakeCheckpointAsync()
|
||||
{
|
||||
// Prompt for an optional description on the UI thread.
|
||||
string? description = null;
|
||||
var prompted = Application.Current.Dispatcher.Invoke(() =>
|
||||
{
|
||||
var dlg = new Views.TakeCheckpointDialog { Owner = Application.Current.MainWindow };
|
||||
if (dlg.ShowDialog() != true) return false;
|
||||
description = string.IsNullOrWhiteSpace(dlg.Description) ? null : dlg.Description;
|
||||
return true;
|
||||
});
|
||||
if (!prompted) return;
|
||||
|
||||
try
|
||||
{
|
||||
var entry = await _client.CreateCheckpointAsync(description).ConfigureAwait(false);
|
||||
await RefreshAsync().ConfigureAwait(false);
|
||||
if (entry is not null)
|
||||
{
|
||||
Application.Current.Dispatcher.Invoke(() =>
|
||||
{
|
||||
Selected = Checkpoints.FirstOrDefault(c => c.FileName == entry.FileName);
|
||||
StatusMessage = $"Created {entry.FileName}";
|
||||
});
|
||||
}
|
||||
}
|
||||
catch (Exception ex)
|
||||
{
|
||||
Application.Current.Dispatcher.Invoke(() =>
|
||||
MessageBox.Show(ex.Message, "Take checkpoint failed", MessageBoxButton.OK, MessageBoxImage.Error));
|
||||
}
|
||||
}
|
||||
|
||||
[RelayCommand]
|
||||
private async Task RollbackAsync()
|
||||
{
|
||||
if (Selected is null) return;
|
||||
|
||||
// Capture before the refresh; the ObservableCollection.Clear() in
|
||||
// RefreshAsync nulls Selected (the original instance is gone from the
|
||||
// collection so the SelectedItem binding clears).
|
||||
var fileName = Selected.FileName;
|
||||
var savedAt = Selected.SavedAt;
|
||||
|
||||
var ok = MessageBox.Show(
|
||||
$"Roll the configuration back to the checkpoint from {savedAt.ToLocalTime():yyyy-MM-dd HH:mm:ss}?\n\nThe current configuration is automatically saved as a new checkpoint first, so you can roll forward again.",
|
||||
"Confirm rollback",
|
||||
MessageBoxButton.OKCancel,
|
||||
MessageBoxImage.Warning);
|
||||
if (ok != MessageBoxResult.OK) return;
|
||||
|
||||
try
|
||||
{
|
||||
await _client.RestoreBackupAsync(fileName).ConfigureAwait(false);
|
||||
await RefreshAsync().ConfigureAwait(false);
|
||||
Application.Current.Dispatcher.Invoke(() =>
|
||||
StatusMessage = $"Rolled back to {fileName}.");
|
||||
}
|
||||
catch (Exception ex)
|
||||
{
|
||||
Application.Current.Dispatcher.Invoke(() =>
|
||||
MessageBox.Show(ex.Message, "Rollback failed", MessageBoxButton.OK, MessageBoxImage.Error));
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -29,28 +29,17 @@ public sealed partial class MainViewModel : ObservableObject
|
||||
[ObservableProperty] private ServerConfig _serverConfig = new();
|
||||
[ObservableProperty] private string _httpBaseUrl = "http://localhost:8080";
|
||||
[ObservableProperty] private string? _httpsBaseUrl;
|
||||
[ObservableProperty] private bool _minimizeToTrayEnabled;
|
||||
|
||||
private readonly DispatcherTimer _logTimer;
|
||||
private readonly GuiSettings _settings;
|
||||
|
||||
public MainViewModel(AdminPipeClient client)
|
||||
{
|
||||
_client = client;
|
||||
_settings = GuiSettings.Load();
|
||||
_minimizeToTrayEnabled = _settings.MinimizeToTrayEnabled;
|
||||
|
||||
_logTimer = new DispatcherTimer(DispatcherPriority.Background) { Interval = TimeSpan.FromSeconds(3) };
|
||||
_logTimer.Tick += async (_, _) => await RefreshLogTailAsync();
|
||||
_logTimer.Start();
|
||||
}
|
||||
|
||||
partial void OnMinimizeToTrayEnabledChanged(bool value)
|
||||
{
|
||||
_settings.MinimizeToTrayEnabled = value;
|
||||
_settings.Save();
|
||||
}
|
||||
|
||||
[RelayCommand]
|
||||
private async Task RefreshAsync()
|
||||
{
|
||||
@@ -186,18 +175,39 @@ public sealed partial class MainViewModel : ObservableObject
|
||||
}
|
||||
}
|
||||
|
||||
[ObservableProperty] private System.Collections.ObjectModel.ObservableCollection<BackupEntry> _backups = new();
|
||||
|
||||
[RelayCommand]
|
||||
private void ShowConfigCheckpoints()
|
||||
private async Task RefreshBackupsAsync()
|
||||
{
|
||||
var dlg = new Views.ConfigCheckpointsDialog
|
||||
try
|
||||
{
|
||||
Owner = Application.Current.MainWindow,
|
||||
DataContext = new ConfigCheckpointsViewModel(_client),
|
||||
};
|
||||
dlg.ShowDialog();
|
||||
// After the dialog closes, the live config may have changed via rollback,
|
||||
// so refresh the main grid.
|
||||
_ = RefreshAsync();
|
||||
var list = await _client.ListBackupsAsync().ConfigureAwait(false);
|
||||
Application.Current.Dispatcher.Invoke(() =>
|
||||
{
|
||||
Backups.Clear();
|
||||
foreach (var b in list) Backups.Add(b);
|
||||
});
|
||||
}
|
||||
catch { /* ignore - checkpoint listing isn't critical */ }
|
||||
}
|
||||
|
||||
[RelayCommand]
|
||||
private async Task RestoreBackupAsync(BackupEntry? entry)
|
||||
{
|
||||
if (entry is null) return;
|
||||
var ok = MessageBox.Show(
|
||||
$"Restore the configuration from the checkpoint taken at {entry.SavedAt:yyyy-MM-dd HH:mm}?\n\nThe current configuration is automatically saved as a new checkpoint first, so you can roll forward again.",
|
||||
"Restore checkpoint",
|
||||
MessageBoxButton.OKCancel,
|
||||
MessageBoxImage.Question);
|
||||
if (ok != MessageBoxResult.OK) return;
|
||||
try
|
||||
{
|
||||
await _client.RestoreBackupAsync(entry.FileName).ConfigureAwait(false);
|
||||
await RefreshAsync().ConfigureAwait(false);
|
||||
}
|
||||
catch (Exception ex) { ShowError("Restore failed", ex); }
|
||||
}
|
||||
|
||||
[RelayCommand]
|
||||
@@ -280,31 +290,10 @@ public sealed partial class MainViewModel : ObservableObject
|
||||
dlg.ShowDialog();
|
||||
}
|
||||
|
||||
[RelayCommand]
|
||||
private void OpenDocumentation()
|
||||
{
|
||||
try
|
||||
{
|
||||
System.Diagnostics.Process.Start(new System.Diagnostics.ProcessStartInfo
|
||||
{
|
||||
FileName = "https://github.com/recklessop/webhook-server/tree/main/docs",
|
||||
UseShellExecute = true,
|
||||
});
|
||||
}
|
||||
catch (Exception ex)
|
||||
{
|
||||
ShowError("Could not open documentation", ex);
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>Raised when the user picks File -> Exit. MainWindow flips its
|
||||
/// ExitForReal flag and shuts down, bypassing the X-hides-to-tray logic.</summary>
|
||||
public event Action? RealExitRequested;
|
||||
|
||||
[RelayCommand]
|
||||
private void Exit()
|
||||
{
|
||||
RealExitRequested?.Invoke();
|
||||
Application.Current.Shutdown();
|
||||
}
|
||||
|
||||
[RelayCommand]
|
||||
|
||||
@@ -1,53 +0,0 @@
|
||||
<Window x:Class="WebhookServer.Gui.Views.ConfigCheckpointsDialog"
|
||||
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
|
||||
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
|
||||
xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
|
||||
xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
|
||||
xmlns:vm="clr-namespace:WebhookServer.Gui.ViewModels"
|
||||
mc:Ignorable="d"
|
||||
Title="Config Checkpoints"
|
||||
Height="500" Width="640"
|
||||
Icon="/webhook-server.ico"
|
||||
WindowStartupLocation="CenterOwner"
|
||||
d:DataContext="{d:DesignInstance Type=vm:ConfigCheckpointsViewModel}">
|
||||
<DockPanel Margin="12">
|
||||
<TextBlock DockPanel.Dock="Top" TextWrapping="Wrap" Margin="0,0,0,8" Foreground="#444">
|
||||
A checkpoint is a snapshot of <Bold>config.json</Bold> taken before each save and once a day at midnight.
|
||||
Pick one and click <Bold>Roll Back</Bold> to restore it. The current configuration is automatically saved
|
||||
as a new checkpoint before any rollback, so you can always roll forward again.
|
||||
</TextBlock>
|
||||
|
||||
<StackPanel DockPanel.Dock="Bottom" Orientation="Horizontal" HorizontalAlignment="Right" Margin="0,8,0,0">
|
||||
<Button Content="Take Checkpoint Now" Command="{Binding TakeCheckpointCommand}" Margin="0,0,8,0" Padding="10,4"/>
|
||||
<Button Content="Roll Back" Command="{Binding RollbackCommand}"
|
||||
IsEnabled="{Binding Selected, Converter={StaticResource NotNull}}"
|
||||
Margin="0,0,8,0" Padding="10,4"/>
|
||||
<Button Content="Close" IsCancel="True" Click="OnClose" Padding="10,4"/>
|
||||
</StackPanel>
|
||||
|
||||
<StackPanel DockPanel.Dock="Bottom" Orientation="Horizontal" Margin="0,4,0,0">
|
||||
<Button Content="Refresh" Command="{Binding RefreshCommand}" Padding="8,2"/>
|
||||
<TextBlock Text="{Binding StatusMessage}" Foreground="Gray" FontStyle="Italic" VerticalAlignment="Center" Margin="12,0,0,0"/>
|
||||
</StackPanel>
|
||||
|
||||
<DataGrid ItemsSource="{Binding Checkpoints}"
|
||||
SelectedItem="{Binding Selected, Mode=TwoWay}"
|
||||
AutoGenerateColumns="False"
|
||||
CanUserAddRows="False"
|
||||
CanUserDeleteRows="False"
|
||||
IsReadOnly="True"
|
||||
HeadersVisibility="Column"
|
||||
GridLinesVisibility="Horizontal">
|
||||
<DataGrid.Columns>
|
||||
<DataGridTextColumn Header="When (local)" Width="170"
|
||||
Binding="{Binding SavedAt, StringFormat='{}{0:yyyy-MM-dd HH:mm:ss}', ConverterCulture=en-US}"/>
|
||||
<DataGridTextColumn Header="Description" Width="*"
|
||||
Binding="{Binding Description}"/>
|
||||
<DataGridTextColumn Header="Size" Width="100"
|
||||
Binding="{Binding SizeBytes, StringFormat='{}{0:n0} bytes'}"/>
|
||||
<DataGridTextColumn Header="File name" Width="200"
|
||||
Binding="{Binding FileName}" FontFamily="Consolas"/>
|
||||
</DataGrid.Columns>
|
||||
</DataGrid>
|
||||
</DockPanel>
|
||||
</Window>
|
||||
@@ -1,19 +0,0 @@
|
||||
using System.Windows;
|
||||
using WebhookServer.Gui.ViewModels;
|
||||
|
||||
namespace WebhookServer.Gui.Views;
|
||||
|
||||
public partial class ConfigCheckpointsDialog : Window
|
||||
{
|
||||
public ConfigCheckpointsDialog()
|
||||
{
|
||||
InitializeComponent();
|
||||
Loaded += async (_, _) =>
|
||||
{
|
||||
if (DataContext is ConfigCheckpointsViewModel vm)
|
||||
await vm.RefreshAsync();
|
||||
};
|
||||
}
|
||||
|
||||
private void OnClose(object sender, RoutedEventArgs e) => Close();
|
||||
}
|
||||
@@ -1,34 +0,0 @@
|
||||
<Window x:Class="WebhookServer.Gui.Views.TakeCheckpointDialog"
|
||||
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
|
||||
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
|
||||
Title="Take checkpoint"
|
||||
Height="180" Width="440"
|
||||
ResizeMode="NoResize"
|
||||
WindowStartupLocation="CenterOwner"
|
||||
Icon="/webhook-server.ico"
|
||||
ShowInTaskbar="False">
|
||||
<Grid Margin="16">
|
||||
<Grid.RowDefinitions>
|
||||
<RowDefinition Height="Auto"/>
|
||||
<RowDefinition Height="Auto"/>
|
||||
<RowDefinition Height="Auto"/>
|
||||
<RowDefinition Height="*"/>
|
||||
<RowDefinition Height="Auto"/>
|
||||
</Grid.RowDefinitions>
|
||||
|
||||
<TextBlock Grid.Row="0" TextWrapping="Wrap"
|
||||
Text="Description for this checkpoint (optional):"/>
|
||||
<TextBox x:Name="DescriptionBox" Grid.Row="1" Margin="0,8,0,0" MaxLength="120">
|
||||
<TextBox.InputBindings>
|
||||
<KeyBinding Key="Enter" Command="{Binding OkCommand, ElementName=Self, FallbackValue={x:Null}}"/>
|
||||
</TextBox.InputBindings>
|
||||
</TextBox>
|
||||
<TextBlock Grid.Row="2" Foreground="Gray" FontStyle="Italic" FontSize="11" Margin="0,4,0,0"
|
||||
Text="Examples: 'Before adding new endpoint', 'Pre-AD-policy-change'. Leave blank to use 'Manual checkpoint'."/>
|
||||
|
||||
<StackPanel Grid.Row="4" Orientation="Horizontal" HorizontalAlignment="Right" Margin="0,12,0,0">
|
||||
<Button Content="OK" Width="80" IsDefault="True" Click="OnOk" Margin="0,0,8,0"/>
|
||||
<Button Content="Cancel" Width="80" IsCancel="True" Click="OnCancel"/>
|
||||
</StackPanel>
|
||||
</Grid>
|
||||
</Window>
|
||||
@@ -1,27 +0,0 @@
|
||||
using System.Windows;
|
||||
|
||||
namespace WebhookServer.Gui.Views;
|
||||
|
||||
public partial class TakeCheckpointDialog : Window
|
||||
{
|
||||
public string Description { get; private set; } = "";
|
||||
|
||||
public TakeCheckpointDialog()
|
||||
{
|
||||
InitializeComponent();
|
||||
Loaded += (_, _) => DescriptionBox.Focus();
|
||||
}
|
||||
|
||||
private void OnOk(object sender, RoutedEventArgs e)
|
||||
{
|
||||
Description = DescriptionBox.Text?.Trim() ?? "";
|
||||
DialogResult = true;
|
||||
Close();
|
||||
}
|
||||
|
||||
private void OnCancel(object sender, RoutedEventArgs e)
|
||||
{
|
||||
DialogResult = false;
|
||||
Close();
|
||||
}
|
||||
}
|
||||
@@ -225,65 +225,16 @@ internal sealed class AdminPipeServer : BackgroundService
|
||||
return AdminResponse.Success(SafeSnapshotForWire(_state.Snapshot()));
|
||||
}
|
||||
|
||||
case AdminOps.CreateCheckpoint:
|
||||
{
|
||||
var args = DeserializeData<CreateCheckpointArgs>(request);
|
||||
var description = args?.Description;
|
||||
if (string.IsNullOrWhiteSpace(description)) description = "Manual checkpoint";
|
||||
var entry = CreateCheckpoint("manual", description);
|
||||
_logger.LogInformation("Manual checkpoint created: {File} ({Desc})", entry.FileName, description);
|
||||
return AdminResponse.Success(entry);
|
||||
}
|
||||
|
||||
default:
|
||||
return AdminResponse.Failure($"unknown op '{request.Op}'");
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Snapshot the current config.json into the backups folder. Used by the
|
||||
/// "Take checkpoint now" GUI action, the midnight scheduler, and the
|
||||
/// auto-on-save hook in ConfigStore. Description is stored in a sidecar
|
||||
/// .meta.json file next to the snapshot so it survives restarts and can
|
||||
/// be rendered in the GUI.
|
||||
/// </summary>
|
||||
public static BackupEntry CreateCheckpoint(string reason, string description)
|
||||
{
|
||||
var configPath = ServicePaths.ConfigPath;
|
||||
if (!File.Exists(configPath))
|
||||
throw new FileNotFoundException("no config.json exists yet to snapshot");
|
||||
|
||||
var dir = Path.Combine(ServicePaths.DataRoot, "backups");
|
||||
Directory.CreateDirectory(dir);
|
||||
|
||||
var stamp = DateTime.UtcNow.ToString("yyyyMMdd-HHmmss");
|
||||
var dest = Path.Combine(dir, $"config-{stamp}.json");
|
||||
if (File.Exists(dest))
|
||||
dest = Path.Combine(dir, $"config-{stamp}-{reason}.json");
|
||||
|
||||
File.Copy(configPath, dest);
|
||||
|
||||
// Write the sidecar metadata.
|
||||
var sidecarPath = Path.ChangeExtension(dest, ".meta.json");
|
||||
var sidecar = new { description, reason };
|
||||
File.WriteAllText(sidecarPath, JsonSerializer.Serialize(sidecar, ConfigJson.Compact));
|
||||
|
||||
var info = new FileInfo(dest);
|
||||
return new BackupEntry
|
||||
{
|
||||
FileName = info.Name,
|
||||
SavedAt = info.LastWriteTimeUtc,
|
||||
SizeBytes = info.Length,
|
||||
Description = description,
|
||||
};
|
||||
}
|
||||
|
||||
private static List<BackupEntry> ListBackups()
|
||||
{
|
||||
var dir = Path.Combine(ServicePaths.DataRoot, "backups");
|
||||
if (!Directory.Exists(dir)) return new List<BackupEntry>();
|
||||
return new DirectoryInfo(dir).GetFiles("config-*.json")
|
||||
.Where(f => !f.Name.EndsWith(".meta.json", StringComparison.OrdinalIgnoreCase))
|
||||
.OrderByDescending(f => f.Name)
|
||||
.Take(50)
|
||||
.Select(f => new BackupEntry
|
||||
@@ -291,23 +242,10 @@ internal sealed class AdminPipeServer : BackgroundService
|
||||
FileName = f.Name,
|
||||
SavedAt = f.LastWriteTimeUtc,
|
||||
SizeBytes = f.Length,
|
||||
Description = ReadSidecarDescription(f.FullName),
|
||||
})
|
||||
.ToList();
|
||||
}
|
||||
|
||||
private static string? ReadSidecarDescription(string snapshotPath)
|
||||
{
|
||||
try
|
||||
{
|
||||
var sidecarPath = Path.ChangeExtension(snapshotPath, ".meta.json");
|
||||
if (!File.Exists(sidecarPath)) return null;
|
||||
using var doc = JsonDocument.Parse(File.ReadAllText(sidecarPath));
|
||||
return doc.RootElement.TryGetProperty("description", out var d) ? d.GetString() : null;
|
||||
}
|
||||
catch { return null; }
|
||||
}
|
||||
|
||||
private async Task<ServerConfig> RestoreBackupAsync(string fileName, CancellationToken ct)
|
||||
{
|
||||
// Refuse anything that tries to escape the backups directory.
|
||||
|
||||
@@ -1,50 +0,0 @@
|
||||
using System.Runtime.Versioning;
|
||||
using Microsoft.Extensions.Hosting;
|
||||
using Microsoft.Extensions.Logging;
|
||||
|
||||
namespace WebhookServer.Service;
|
||||
|
||||
/// <summary>
|
||||
/// Creates a daily config checkpoint at midnight (local time). Combined with
|
||||
/// the auto-on-save snapshots in ConfigStore.SaveAsync, this guarantees a
|
||||
/// rollback point for every day even if the user makes no changes.
|
||||
/// </summary>
|
||||
[SupportedOSPlatform("windows")]
|
||||
internal sealed class CheckpointScheduler : BackgroundService
|
||||
{
|
||||
private readonly ILogger<CheckpointScheduler> _logger;
|
||||
|
||||
public CheckpointScheduler(ILogger<CheckpointScheduler> logger)
|
||||
{
|
||||
_logger = logger;
|
||||
}
|
||||
|
||||
protected override async Task ExecuteAsync(CancellationToken stoppingToken)
|
||||
{
|
||||
_logger.LogInformation("Daily checkpoint scheduler running");
|
||||
|
||||
while (!stoppingToken.IsCancellationRequested)
|
||||
{
|
||||
var now = DateTime.Now;
|
||||
var nextMidnight = now.Date.AddDays(1);
|
||||
var delay = nextMidnight - now;
|
||||
|
||||
try { await Task.Delay(delay, stoppingToken).ConfigureAwait(false); }
|
||||
catch (OperationCanceledException) { return; }
|
||||
|
||||
try
|
||||
{
|
||||
var entry = AdminPipeServer.CreateCheckpoint("daily", "Nightly auto-checkpoint");
|
||||
_logger.LogInformation("Daily checkpoint created: {File}", entry.FileName);
|
||||
}
|
||||
catch (FileNotFoundException)
|
||||
{
|
||||
// No config.json yet (fresh install, GUI never opened) - skip silently.
|
||||
}
|
||||
catch (Exception ex)
|
||||
{
|
||||
_logger.LogWarning(ex, "Daily checkpoint creation failed");
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -49,7 +49,6 @@ try
|
||||
builder.Services.AddSingleton<WebhookRouter>();
|
||||
builder.Services.AddHostedService<CallbackBackgroundService>();
|
||||
builder.Services.AddHostedService<AdminPipeServer>();
|
||||
builder.Services.AddHostedService<CheckpointScheduler>();
|
||||
|
||||
var app = builder.Build();
|
||||
|
||||
|
||||
Reference in New Issue
Block a user