ICS Feed Monitor

A WordPress plugin that monitors ICS (iCalendar) feed polling by booking platforms. Designed for short-term rental property managers who list on multiple platforms (Airbnb, VRBO, Booking.com, etc.), it detects when a platform silently stops syncing your availability calendar — before double-bookings happen.

How It Works

Instead of giving booking platforms your real ICS feed URL, you give them a proxy URL generated by this plugin. The proxy:

1. Passes through the real ICS data transparently to the requesting platform
2. Logs every poll — recording timestamp, IP address, user agent, and response time
3. Fires alerts via webhook if a platform stops polling within your configured threshold

A WordPress cron job runs hourly to check for stale feeds and send notifications.

Features

• Transparent ICS proxy — REST API endpoint that fetches and forwards ICS data without altering it
• Per-feed alert windows — configure how many hours of silence triggers an alert (default: 6 hours)
• Webhook alerts — POST or GET notifications with HMAC-SHA256 signatures for stale feeds and upstream errors
• Healthcheck pings — integrates with healthchecks.io, Cronitor, Better Uptime, or any heartbeat service
• Dashboard — at-a-glance status cards grouped by apartment with colour-coded feed health
• Poll history — per-feed log of every poll with IP, user agent, status, and response time
• Structured logging — filterable system log with level, source, and JSON context
• Rate limiting — 60 requests/hour per feed token to prevent abuse
• Auto-updates — checks GitHub Releases for new versions via the standard WordPress update mechanism
• Multi-platform support — built-in badges for Airbnb, VRBO, Booking.com, and custom platforms

Requirements

• PHP 7.4+
• WordPress 5.0+ (REST API required)

Installation

1. Download the latest release from GitHub Releases
2. Upload to wp-content/plugins/ics-feed-monitor/
3. Activate the plugin in WordPress
4. Navigate to ICS Monitor → Settings to configure your webhook URL

Setup

1. Add Apartments

Go to ICS Monitor → Apartments and add your rental properties.

2. Add Feeds

Go to ICS Monitor → Feeds and for each apartment/platform combination:

• Select the apartment and platform (Airbnb, VRBO, Booking.com, or Other)
• Enter the source ICS URL — the real calendar feed URL from the booking platform
• Set an alert window in hours (how long before silence triggers an alert)
• Save to generate a proxy URL

3. Use the Proxy URLs

Copy the generated proxy URL and give it to the booking platform instead of the real ICS URL. The plugin will transparently forward the calendar data while monitoring poll activity.

4. Configure Alerts

In ICS Monitor → Settings:

• Webhook URL — where to send alerts (Zapier, Make, ntfy.sh, Slack incoming webhook, custom endpoint, etc.)
• Webhook method — POST (JSON body) or GET (query parameters)
• Healthcheck URL — optional heartbeat ping to confirm the cron job is running
• Alert cooldown — minimum hours between repeat alerts for the same feed

5. Cron Setup (Recommended)

The plugin uses WP-Cron by default. For reliable scheduling, set up a system cron job:

Add to your crontab (crontab -e):

*/5 * * * * wget -qO- https://yoursite.com/wp-cron.php?doing_wp_cron > /dev/null 2>&1

Then add to wp-config.php:

define('DISABLE_WP_CRON', true);

Configuration Constants

Optional constants for wp-config.php:

Constant	Description
ICSFM_WEBHOOK_SECRET	Override the webhook HMAC signing secret
ICSFM_GITHUB_TOKEN	GitHub API token for update checks on private repos

Feed Status Indicators

Status	Colour	Meaning
Healthy	Green	Polled within the last 50% of the alert window
Approaching	Yellow	Polled, but past the 50% mark of the alert window
Stale	Red	Not polled within the alert window — alert sent

Webhook Payloads

All webhooks include an X-ICSFM-Signature header containing sha256=<HMAC-SHA256 hex digest> for verification.

Event: feed_stale

Fired when a feed has not been polled within its alert window.

{
  "event": "feed_stale",
  "feed_id": 1,
  "feed_label": "Beachside Cottage — Airbnb",
  "apartment": "Beachside Cottage",
  "platform": "airbnb",
  "proxy_url": "https://yoursite.com/wp-json/icsfm/v1/feed/<token>",
  "last_polled_at": "2025-01-15 10:30:00",
  "hours_since_poll": 8.5,
  "last_fetch_status": "ok",
  "alert_window_hours": 6,
  "timestamp": "2025-01-15T18:30:00+00:00"
}

Event: upstream_error

Fired when the source ICS URL returns an error during a proxy request.

Event: test

Manually triggered from the settings page to verify webhook connectivity.

Database

The plugin creates four custom tables on activation and removes them on uninstall:

• {prefix}icsfm_apartments — rental properties
• {prefix}icsfm_feeds — ICS feed configurations and proxy tokens
• {prefix}icsfm_poll_log — per-request poll history
• {prefix}icsfm_log — structured system log

Author

Nonatech UK

License

This project is proprietary software. All rights reserved.