What are Webhooks?

Webhooks are a way for Thieves to send real-time notifications to other applications when your monitoring conditions are met. Think of them as automated messages that Thieves sends to a URL you provide. Instead of your application constantly asking Thieves, "Has anything changed?", Thieves proactively tells your application, "Yes, something just happened!"

Webhook Output Format

When a check cycle completes, Thieves sends a POST request to your specified webhook URL with a JSON payload. The payload structure is as follows:

{
    "tracker_id": "integer",
    "tracker_name": "string",
    "checked_at": "string (ISO 8601 datetime)",
    "condition": "string",
    "running": "boolean",
    "check_frequency":  "integer (seconds)",
    "urls": "array of strings",
    "result": "boolean",
    "matches": "array of objects",
    "failures": "array of objects"
}
                

• tracker_id: The unique integer ID of the tracker.
• tracker_name: The custom name you gave the tracker.
• checked_at: The timestamp when the check was performed in UTC (ISO 8601 format).
• condition: The condition that was evaluated.
• running: A boolean indicating if the tracker is currently active.
• check_frequency: How often the check is performed, in seconds.
• urls: A list of all the URLs being monitored by this tracker.
• result: A simple boolean flag. It is true if one or more URLs met the condition.
• matches: An array of result objects, one for each URL that **met** the condition. Each object has the following structure:
  • url: The specific URL that met the condition.
  • description: A string explaining how the condition was met (e.g., the new price found).
• failures: An array of result objects, one for each URL that was checked but did **not** meet the condition. Each object has the following structure:
  • url: The specific URL that did not meet the condition.
  • description: A string explaining why the condition was not met (e.g., the price was still too high).

Example Payload

Here is an example where a tracker monitoring three pages finds that two met the condition, while one did not.

{
    "tracker_id": 125,
    "tracker_name": "Acme Laptop Price Watch",
    "checked_at": "2025-07-20T10:30:00Z",
    "condition": "The price is below $1000",
    "running": true,
    "check_frequency": 3600,
    "urls": [
        "https://example.com/product/acme-laptop-pro",
        "https://example.com/product/acme-laptop-air",
        "https://example.com/product/acme-laptop-ultra"
    ],
    "result": true,
    "matches": [
        {
            "url": "https://example.com/product/acme-laptop-pro",
            "description": "The price is now $999, which is below the $1000 condition."
        },
        {
            "url": "https://example.com/product/acme-laptop-air",
            "description": "The price is now $950, which is below the $1000 condition."
        }
    ],
    "failures": [
        {
            "url": "https://example.com/product/acme-laptop-ultra",
            "description": "The price is $1199, which is not below the $1000 condition."
        }
    ]
}