Python guide

Add a Verifagent heartbeat to a Python script

Call Verifagent at the end of the script, after the work that must succeed. If the process crashes earlier, the missing heartbeat is the alert.

Before you start

Create a monitor with your workflow’s real frequency, then copy its URL from the dashboard. Its token is secret: do not publish it.

Module to use : requests / urllib. Place it after the last useful action on the success path.

Setup

Copy the monitor URL

Create a monitor for this script’s schedule. Keep the URL in an environment variable, not in source control.

https://verifagent.com/api/ping/your-ping-token

Version with requests

Install requests if needed (pip install requests). Raise on failure so a bad ping fails the process after successful work — still only call ping after the work block.

import os

import requests

PING_URL = os.environ["VERIFAGENT_URL"]  # full monitor URL

def main() -> None:
    # 1) Real work first
    do_work()

    # 2) Heartbeat only after success
    response = requests.get(PING_URL, timeout=15)
    response.raise_for_status()
    print(response.json())  # {"ok": true}

def do_work() -> None:
    # Replace with your job
    ...

if __name__ == "__main__":
    try:
        main()
    except Exception:
        # No ping on failure — Verifagent will notice the silence
        raise

Version with urllib (no dependency)

Same order: work first, then GET. urllib is in the standard library.

import json
import os
import urllib.request

PING_URL = os.environ["VERIFAGENT_URL"]

def ping() -> None:
    with urllib.request.urlopen(PING_URL, timeout=15) as resp:
        body = json.load(resp)
        if resp.status != 200 or body.get("ok") is not True:
            raise RuntimeError(f"Unexpected ping response: {body!r}")

def main() -> None:
    do_work()
    ping()

def do_work() -> None:
    ...

if __name__ == "__main__":
    main()

Schedule and verify

Export VERIFAGENT_URL, run the script once, expect {"ok": true}. Wire it to cron or systemd with the same environment.

{"ok":true}

Never ping at the top of main(). Align expected period with how often the script runs; grace should cover max runtime plus scheduler jitter.

Available routes

The base URL is enough for a heartbeat. Variants enrich history if your platform has several branches.

GET https://YOUR_PING_URL

POST https://YOUR_PING_URL/success

POST https://YOUR_PING_URL/fail?msg=Error

Verify

A successful run flips the monitor to Up. Force an exception before ping() and confirm Verifagent receives nothing for that run.

Expected response: 200 {"ok":true}. The monitor moves from Pending to Up.