Allow arbitrary URLs for success hooks

An extension to #56.

Author: RealOrangeOne

README.md

@@ -19,7 +19,13 @@ Mount your backup directory as `/var/backups` (or override `$BACKUP_DIR`). Backu
 
 Backups run daily at midnight. To change this, add a cron-style schedule to `$SCHEDULE`. For more information on the format of the cron strings, please see the [croniter documentation on PyPI](https://pypi.org/project/croniter/).
 
-Additionally, there is support for [healthchecks.io](https://healthchecks.io) and [Uptime Kuma](https://github.com/louislam/uptime-kuma/) for monitoring purposes. `$HEALTHCHECKS_ID` can be used to specify the id to ping. If you're using a self-hosted instance, set `$HEALTHCHECKS_HOST`. To use the generated URL by the Monitor Type `Push` in Uptime Kuma, set `$UPTIME_KUMA_URL`.
+### Success hooks
+
+When backups are completed successfully, a request can be made to the URL defined in `$SUCCESS_HOOK_URL`. By default, a `GET` request is made. To include logs, also set `$INCLUDE_LOGS` to a non-empty value, which sends a `POST` request instead with helpful details in the body.
+
+Note: Previous versions also supported `$HEALTHCHECKS_ID`, `$HEALTHCHECKS_HOST` and `$UPTIME_KUMA_URL`, or native support for [healthchecks.io](https://healthchecks.io) and [Uptime Kuma](https://github.com/louislam/uptime-kuma/) respectively. These are all still supported, however `$SUCCESS_HOOK_URL` is preferred.
+
+### Compression
 
 Files are backed up uncompressed by default, on the assumption a snapshotting or native compressed filesystem is being used (eg ZFS). To enable compression, set `$COMPRESSION` to one of the supported algorithms:
 
@@ -41,7 +47,8 @@ services:
       - /var/run/docker.sock:/var/run/docker.sock:ro
       - ./backups:/var/backups
     environment:
-      - HEALTHCHECKS_ID=id
+      - SUCCESS_HOOK_URL=https://hc-ping.com/1234
+      - INCLUDE_LOGS=true
 ```
 
 ### Oneshot

db-auto-backup.py

@@ -79,6 +79,20 @@ def get_compressed_file_extension(algorithm: str) -> str:
     raise ValueError(f"Unknown compression method {algorithm}")
 
 
+def get_success_hook_url() -> Optional[str]:
+    if success_hook_url := os.environ.get("SUCCESS_HOOK_URL"):
+        return success_hook_url
+
+    if healthchecks_id := os.environ.get("HEALTHCHECKS_ID"):
+        healthchecks_host = os.environ.get("HEALTHCHECKS_HOST", "hc-ping.com")
+        return f"https://{healthchecks_host}/{healthchecks_id}"
+
+    if uptime_kuma_url := os.environ.get("UPTIME_KUMA_URL"):
+        return uptime_kuma_url
+
+    return None
+
+
 def backup_psql(container: Container) -> str:
     env = get_container_env(container)
     user = env.get("POSTGRES_USER", "postgres")
@@ -131,6 +145,7 @@ def backup_redis(container: Container) -> str:
 SCHEDULE = os.environ.get("SCHEDULE", "0 0 * * *")
 SHOW_PROGRESS = sys.stdout.isatty()
 COMPRESSION = os.environ.get("COMPRESSION", "plain")
+INCLUDE_LOGS = bool(os.environ.get("INCLUDE_LOGS"))
 
 
 def get_backup_provider(container_names: Sequence[str]) -> Optional[BackupProvider]:
@@ -187,15 +202,15 @@ def backup(now: datetime) -> None:
     duration = (datetime.now() - now).total_seconds()
     print(f"Backup complete in {duration:.2f} seconds.")
 
-    if healthchecks_id := os.environ.get("HEALTHCHECKS_ID"):
-        healthchecks_host = os.environ.get("HEALTHCHECKS_HOST", "hc-ping.com")
-        requests.post(
-            f"https://{healthchecks_host}/{healthchecks_id}",
-            data="\n".join(backed_up_containers),
-        ).raise_for_status()
+    if success_hook_url := get_success_hook_url():
+        if INCLUDE_LOGS:
+            response = requests.post(
+                success_hook_url, data="\n".join(backed_up_containers)
+            )
+        else:
+            response = requests.get(success_hook_url)
 
-    if uptime_kuma_url := os.environ.get("UPTIME_KUMA_URL"):
-        requests.get(uptime_kuma_url).raise_for_status()
+        response.raise_for_status()
 
 
 if __name__ == "__main__":

tests/tests.py

@@ -69,3 +69,24 @@ def test_backup_runs_compressed(
 )
 def test_compressed_file_extension(algorithm: str, extension: str) -> None:
     assert db_auto_backup.get_compressed_file_extension(algorithm) == extension
+
+
+def test_success_hook_url(monkeypatch: Any) -> None:
+    monkeypatch.setenv("SUCCESS_HOOK_URL", "https://example.com")
+    assert db_auto_backup.get_success_hook_url() == "https://example.com"
+
+
+def test_healthchecks_success_hook_url(monkeypatch: Any) -> None:
+    monkeypatch.setenv("HEALTHCHECKS_ID", "1234")
+    assert db_auto_backup.get_success_hook_url() == "https://hc-ping.com/1234"
+
+
+def test_healthchecks_success_hook_url_custom_host(monkeypatch: Any) -> None:
+    monkeypatch.setenv("HEALTHCHECKS_ID", "1234")
+    monkeypatch.setenv("HEALTHCHECKS_HOST", "my-healthchecks.com")
+    assert db_auto_backup.get_success_hook_url() == "https://my-healthchecks.com/1234"
+
+
+def test_uptime_kuma_success_hook_url(monkeypatch: Any) -> None:
+    monkeypatch.setenv("UPTIME_KUMA_URL", "https://uptime-kuma.com")
+    assert db_auto_backup.get_success_hook_url() == "https://uptime-kuma.com"