🔔 Change Detection & Webhooks

Automatically monitor URLs for metadata changes and get notified via webhooks. Perfect for SEO monitoring, competitor tracking, and content auditing.

Endpoints

POST/v1/monitorsCreate a new monitor

GET/v1/monitorsList all monitors

GET/v1/monitors/:idGet monitor details

PATCH/v1/monitors/:idUpdate a monitor

DELETE/v1/monitors/:idDelete a monitor

GET/v1/monitors/:id/historyGet change history

POST/v1/monitors/:id/checkTrigger manual check

Create Monitor - Request Body

Name	Type	Default	Description
`url`	`string`	-	URL to monitor
`name`	`string`	-	Display name (default: hostname)
`interval`	`enum`	`daily`	hourly \| daily \| weekly
`webhook_url`	`string`	-	URL to receive change notifications
`webhook_secret`	`string`	-	Secret for HMAC signature (auto-generated if not provided)
`notify_on`	`array`	`["any"]`	Fields to monitor: title, description, image, any
`is_active`	`boolean`	`true`	Enable/disable the monitor

Create Monitor Example

curl -X POST "https://api.katsau.com/v1/monitors" \
  -H "Authorization: Bearer ks_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://competitor.com",
    "name": "Competitor Homepage",
    "interval": "daily",
    "webhook_url": "https://myapp.com/webhooks/katsau",
    "notify_on": ["title", "description", "image"]
  }'

Response

{
  "success": true,
  "data": {
    "monitor_id": "mon_abc123xyz",
    "url": "https://competitor.com",
    "name": "Competitor Homepage",
    "interval": "daily",
    "status": "active",
    "webhook_url": "https://myapp.com/webhooks/katsau",
    "webhook_secret": "whsec_a1b2c3d4e5f6g7h8...",
    "notify_on": ["title", "description", "image"],
    "next_check": "2024-01-16T00:00:00Z",
    "created_at": "2024-01-15T12:00:00Z"
  },
  "meta": { "request_id": "req_abc123" }
}

Webhook Payload

When changes are detected, we send a POST request to your webhook URL:

{
  "event": "metadata.changed",
  "timestamp": "2024-01-15T14:00:00Z",
  "monitor_id": "mon_abc123xyz",
  "url": "https://competitor.com",
  "changes": [
    {
      "field": "title",
      "old_value": "Old Title",
      "new_value": "New Title"
    },
    {
      "field": "open_graph.image",
      "old_value": "https://old-image.jpg",
      "new_value": "https://new-image.jpg"
    }
  ],
  "current_metadata": { ... },
  "previous_metadata": { ... }
}

Webhook Security

Each webhook includes an HMAC signature for verification:

Header	Description
`X-katsau-Signature`	HMAC-SHA256 signature of the payload
`X-katsau-Event`	Event type (e.g., metadata.changed)

// Verify webhook signature
const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Plan Limits

Plan	Availability	Max Monitors
Free	Not Available	-
Starter	Not Available	-
Pro	Not Available	-
Enterprise	Included	Custom