Setup Webhooks

Fresh

Webhooks let you receive real-time HTTP notifications when feeds in your RSS.app account are updated with new items. Instead of polling the API repeatedly to check for new content, you register an endpoint and RSS.app pushes updates to you automatically.

How RSS.app Webhooks Work

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

You can configure webhooks to fire for:

• All feeds in your account
• A specific bundle (only feeds within that bundle trigger the webhook)
• A single specific feed

You can also set up custom filters so only items matching certain criteria trigger the webhook.

Prerequisites

• A publicly accessible HTTPS endpoint that can receive POST requests
• RSS.app account with API access and webhook configuration available
• At least one feed created in your account

Step 1: Create Your Webhook Endpoint

Your endpoint must:

• Accept HTTP POST requests
• Read a JSON body
• Return HTTP 200 within a reasonable timeout (typically 5-10 seconds)
• Be accessible from the public internet over HTTPS

Here is a minimal Express.js webhook handler:

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

app.use(express.json());

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

  console.log('Webhook received:', event.type);
  console.log('Feed ID:', event.feed.id);
  console.log('New items:', event.data.items_new.length);
  console.log('Changed items:', event.data.items_changed.length);

  // Process the event asynchronously so you respond quickly
  processWebhookEvent(event).catch(console.error);

  // Always respond 200 immediately
  res.status(200).json({ received: true });
});

async function processWebhookEvent(event) {
  const { feed, data } = event;
  const newItems = data.items_new || [];
  const changedItems = data.items_changed || [];

  for (const item of newItems) {
    console.log('New item:', item.title, item.url);
    // Save to database, trigger notification, etc.
  }

  for (const item of changedItems) {
    console.log('Updated item:', item.title, item.url);
  }
}

app.listen(3000, () => console.log('Webhook server running on port 3000'));

Step 2: Configure the Webhook in RSS.app

Webhook configuration is done through the RSS.app web interface at the API settings page. The API itself does not expose endpoints for creating or managing webhook subscriptions programmatically — this is handled through the account dashboard.

In the webhook configuration:

1. Enter your webhook URL (must be HTTPS)
2. Choose the scope: all feeds, a specific bundle, or a single feed
3. Optionally configure keyword or content filters
4. Save the configuration

Step 3: Understand the Event Payload

Every webhook event follows 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/new-article",
        "title": "New Article Title",
        "description_text": "Plain text summary...",
        "description_html": "<p>HTML summary...</p>",
        "thumbnail": "https://techcrunch.com/image.jpg",
        "authors": [{ "name": "Reporter Name" }],
        "date_published": "2024-01-15T16:00:00Z"
      }
    ],
    "items_changed": []
  }
}

The type field will always be "feed_update" for the current API version.

items_new contains items that appeared for the first time in this feed update.

items_changed contains items that existed previously but were modified — typically an update to the title, description, or content.

Step 4: Handle Retries and Failures

RSS.app will retry failed webhook deliveries if your endpoint returns a non-2xx status or times out. To handle this safely:

Make your webhook handler idempotent. If the same event is delivered twice, processing it twice should not create duplicate records or send duplicate notifications.

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

  // Check if we already processed this event
  const alreadyProcessed = await db.webhookEvents.exists({ eventId: event.id });
  if (alreadyProcessed) {
    return res.status(200).json({ received: true, duplicate: true });
  }

  // Mark as received before processing
  await db.webhookEvents.insert({ eventId: event.id, receivedAt: new Date() });

  // Process asynchronously
  processWebhookEvent(event).catch(console.error);

  res.status(200).json({ received: true });
});

Step 5: Monitor Webhook History

RSS.app provides a webhook delivery history in the API settings page. This log shows:

• Timestamps of delivery attempts
• HTTP status codes returned by your endpoint
• The payload sent on each attempt
• Whether the delivery succeeded or is pending retry

Check this history when debugging integration issues or verifying that your endpoint is receiving events correctly.

Common Issues

Webhook not firing: Verify the feed is active (is_active: true) and the configuration is saved in the account dashboard. New feeds may take a few minutes to start producing events.

Getting items_new as empty: The webhook fires on detected changes to the feed. If the source site hasn't published anything new since the last check interval, the new items array will be empty or the webhook may not fire at all.

Endpoint returns timeout: Your handler must return 200 quickly. Move all processing to an async queue or background job and return the response before doing any heavy lifting.

Duplicate events: Implement idempotency using the event id field as described in Step 4.