From 3d8cf46a6309c5ff385e80361317b55e63634e85 Mon Sep 17 00:00:00 2001
From: Ops Agent <ops-agent@localhost>
Date: Sun, 11 Oct 2026 08:47:14 +0200
Subject: [PATCH] Document webhook target, automatic restoration and complete
 removal

---
 README.md        | 10 ++++++++++
 docs/WEBHOOKS.md | 14 ++++++++++++++
 2 files changed, 24 insertions(+)

diff --git a/README.md b/README.md
index 80f4b43..c2628cc 100644
--- a/README.md
+++ b/README.md
@@ -34,6 +34,16 @@ Live bridge commands require **Windows x64 and 64-bit Python**. They were tested
 
 `send-self` actually sends a message. It is never part of the default tests and does not retry automatically. ZIP exports cover the local database, not necessarily every message ever received. Contacts are local table rows, not a deduplicated phone address book.
 
+## Message listener with automatic restoration
+
+Supply your endpoint token through `WHATSAPP_INJECTOR_WEBHOOK_TOKEN` using your secret manager, then run:
+
+```powershell
+python whatsapp.py webhook install --endpoint https://your-endpoint.example/events --auto-restore --config listener.json
+```
+
+`--endpoint` selects the HTTPS target; `--auto-restore` creates a per-user Windows task that checks every minute and restores the listener after WhatsApp restarts. Delivery runs inside WhatsApp, without CDP, UI automation, a local HTTP server or a continuously running Python process. Add `--self-only` for self-chat testing. The endpoint must authenticate the token header and accept message batches. See [setup, payload, limitations and full removal](docs/WEBHOOKS.md).
+
 ## Development
 
 ```powershell
diff --git a/docs/WEBHOOKS.md b/docs/WEBHOOKS.md
index 1ce96bf..6e56625 100644
--- a/docs/WEBHOOKS.md
+++ b/docs/WEBHOOKS.md
@@ -40,6 +40,20 @@ python whatsapp.py webhook stop --config listener.json
 
 Then stop the receiver with Ctrl+C. Re-enable with `webhook install --restore --config listener.json`. Stopping only the injected listener without disabling a restoring configuration causes the receiver to reinstall it.
 
+### Completely remove automatic restoration
+
+`stop --config` disables restoration in the configuration, but keeps the scheduled task registered. To remove it entirely, first disable the exact task named in your configuration, then stop the listener and unregister that task:
+
+```powershell
+$listenerConfig = Get-Content -LiteralPath listener.json -Raw | ConvertFrom-Json
+Disable-ScheduledTask -TaskName $listenerConfig.restore_task | Out-Null
+python whatsapp.py webhook stop --config listener.json
+Unregister-ScheduledTask -TaskName $listenerConfig.restore_task -Confirm:$false
+Remove-Item -LiteralPath listener.json
+```
+
+These task commands apply only when `--auto-restore` was used. Remove the adjacent `listener.status.json` diagnostic file if present. Restart WhatsApp normally to unload the stopped helper DLL; the listener stays absent because the task is removed. No WhatsApp package files need restoring. The development workstation's test task and protected configuration were removed after validation, and WhatsApp was restarted to clear the injected listener/helper.
+
 ## Payload and integration
 
 The loopback endpoint is `POST /whatsapp-webhook` on `127.0.0.1`; direct HTTPS uses the explicitly configured URL. Batches include `listener_id`, `seqs` and `events`. Each message event includes a sequence number, message ID, chat ID, timestamp, direction, message type, body/caption and text-length/truncation metadata. The built-in receiver persists events in SQLite; an external receiver can feed them to a summarizer. No AI provider or automatic replies are configured.