Webhooks

Fresh

Webhooks provide real-time HTTP notifications when RSS.app detects updates to your monitored feeds. Instead of periodically calling the List Feeds endpoint to check for new content, configure a webhook endpoint and RSS.app pushes updates directly to your server.

Overview

When RSS.app detects new or changed items in a monitored feed, it sends an HTTP POST request to your registered webhook URL. Each request contains a JSON payload describing the feed and what changed.

Webhooks fire for the feed_update event type. There is currently one event type in the API.

Configuration

Webhook subscriptions are configured through the RSS.app account settings page — not through the REST API. In the settings:

1. Navigate to the API settings page at rss.app/account/api
2. Locate the Webhooks section
3. Enter your webhook endpoint URL (must be HTTPS)
4. Choose the subscription scope:
   • All feeds in your account
   • A specific bundle (only feeds in that bundle trigger the webhook)
   • A single specific feed
5. Optionally configure content filters
6. Save the configuration

You can configure multiple webhooks with different scopes and filters.

Event Object

Every webhook delivery sends a JSON payload with this structure:

{
  "id": "evt_abc123",
  "type": "feed_update",
  "feed": {
    "id": "feed_xyz789",
    "title": "TechCrunch",
    "source_url": "https://techcrunch.com",
    "rss_feed_url": "https://rss.app/feeds/your-feed-id.xml",
    "description": "Latest technology news",
    "icon": "https://techcrunch.com/favicon.ico",
    "is_active": true
  },
  "data": {
    "items_new": [
      {
        "url": "https://techcrunch.com/2024/01/15/article-slug",
        "title": "New Article Title",
        "description_text": "Plain text article summary here.",
        "description_html": "<p>HTML article summary here.</p>",
        "thumbnail": "https://techcrunch.com/wp-content/uploads/image.jpg",
        "authors": [
          { "name": "Reporter Name" }
        ],
        "date_published": "2024-01-15T16:00:00Z"
      }
    ],
    "items_changed": []
  }
}

Event Object Fields

Field	Type	Description
id	string	Unique event identifier — use for deduplication
type	string	Always "feed_update"
feed	object	The feed that triggered the event
data.items_new	array	Items that appeared in the feed for the first time
data.items_changed	array	Items that existed before but were modified

Feed Object in Events

The feed object embedded in the event payload contains:

Field	Type	Description
id	string	Feed ID
title	string	Feed display title
source_url	string or null	Source website URL
rss_feed_url	string	Distributable RSS feed URL
description	string or null	Feed description
icon	string or null	Feed icon URL
is_active	boolean	Whether the feed is actively monitored

Handling Webhook Events

Your endpoint must:

• Accept POST requests with a JSON body
• Return HTTP 200 within the response timeout (5-10 seconds)
• Be accessible over the public internet via HTTPS

Minimal Express.js handler:

const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhooks/rssapp', (req, res) => {
  const event = req.body;

  // Respond immediately — process asynchronously
  res.status(200).json({ received: true });

  handleEvent(event).catch(console.error);
});

async function handleEvent(event) {
  if (event.type !== 'feed_update') return;

  const { feed, data } = event;

  for (const item of data.items_new) {
    console.log(`New item in "${feed.title}": ${item.title}`);
    // Store in database, send notification, trigger workflow, etc.
  }

  for (const item of data.items_changed) {
    console.log(`Updated item in "${feed.title}": ${item.title}`);
  }
}

app.listen(3000);

Idempotency

RSS.app retries webhook deliveries on failure. Your handler may receive the same event more than once. Use the event id field to deduplicate:

app.post('/webhooks/rssapp', async (req, res) => {
  const event = req.body;

  const alreadyHandled = await db.processedEvents.exists({ eventId: event.id });
  if (alreadyHandled) {
    return res.status(200).json({ received: true, duplicate: true });
  }

  await db.processedEvents.insert({ eventId: event.id });

  res.status(200).json({ received: true });
  handleEvent(event).catch(console.error);
});

Subscription Scopes

Scope	When webhook fires
All feeds	Any feed update in your account
Specific bundle	Updates only in feeds belonging to that bundle
Single feed	Updates in one specific feed

Use bundle-scoped webhooks to separate concerns. For example, a "client news" bundle webhook goes to your CRM, while a "competitive intelligence" bundle webhook goes to your analytics system.

Custom Filters

Webhook filters let you narrow which events trigger a delivery. For example, filter to only fire when a specific keyword appears in the item title. Filter configuration is available in the webhook settings in the account dashboard.

Delivery History and Monitoring

The RSS.app account settings page shows a delivery history log for each configured webhook. The log includes:

• Delivery timestamp
• HTTP status code returned by your endpoint
• Whether the delivery succeeded or is pending retry
• The full request payload sent

Use this log to debug endpoint issues and verify your integration is receiving events as expected.