RssHub Trigger Plugin

Receive RssHub feed notifications in Dify via simple webhooks. Flexible events, rich filters, and optional shared-secret verification.

Why this plugin

• Reduce polling: trigger workflows as soon as a feed changes.
• Normalize payloads: pass through standard RSS/Atom fields or custom structures.
• Keep it simple: optional API Key, no server-to-server handshake required.

What is RSS Hub?

• RSS Hub is an open‑source project that generates RSS/Atom feeds for websites and services.
• Project homepage (GitHub): https://github.com/DIYgod/RSSHub
• This plugin is the webhook receiver: it accepts feed_update payloads and triggers Dify workflows.

Features

• Optional API Key verification (header or query param)
• Multiple events with sensible defaults
• Rich, per‑event filters to minimize noise
• Generic item payload passthrough as trigger variables

Architecture

• Sender: your RssHub deployment, a cron/worker that reads the feed, or any script that transforms a feed update into a JSON POST.
• Receiver: this plugin’s webhook URL (generated by Dify for the trigger). It validates (optionally) and dispatches an event to your workflow.

Setup

1. Install/import the plugin into Dify.
2. Subscription configuration:
   • API Key (optional):
     • If provided, all webhook calls must include the same key (see Authentication).
     • If left blank, the webhook accepts unauthenticated posts.
3. Copy the generated webhook endpoint URL from your Dify trigger.
4. Configure your RssHub (or a small companion worker) to POST updates to this URL.
   • If using an API Key, include it as described below.
5. (Optional) If you send a custom event name via header/query/body, it will be accepted, but the plugin is optimized for feed_update.

Authentication (Optional)

• Provide a shared API Key in the subscription to enable verification.
• Send the same key with each request using one of:
  • HTTP header X-Api-Key: <your_api_key> (recommended)
  • HTTP header Authorization: Bearer <your_api_key>
  • Query string ?token=<your_api_key> or ?api_key=<your_api_key>
• If you do not configure an API Key in the subscription, the receiver accepts unauthenticated requests.

Event Type

• feed_update
  • This plugin uses a single event, feed_update, and expects the payload structure described in this README.
  • Reference (project): https://github.com/DIYgod/RSSHub
  • Other custom event names are accepted but are not schema-typed.

Payload Schema (rss.app)

The plugin exposes the entire JSON body as trigger variables. The canonical schema is:

• id (string): Unique identifier for the webhook event
• type (string): Event type (currently feed_update)
• feed (object): Feed metadata
  • id (string): Unique identifier for the feed
  • title (string): Feed title
  • source_url (string): Source website URL
  • rss_feed_url (string): RSS feed XML URL
  • description (string): Feed description
  • icon (string): Favicon/icon URL
• data (object): Update details
  • items_new (array of objects): New items since the last event
    • url (string)
    • title (string)
    • description_text (string)
    • thumbnail (string)
    • date_published (date string)
    • authors (array of objects)
      • name (string)
  • items_changed (array of objects): Updated items since the last event
    • url (string)
    • title (string)
    • description_text (string)
    • thumbnail (string)
    • date_published (date string)
    • authors (array of objects)
      • name (string)

Example (cURL)

• feed_update (no auth):

  curl -X POST '<webhook_url>' \
    -H 'Content-Type: application/json' \
    -d '{
  "data": {
    "items_changed": [],
    "items_new": [
      {
        "authors": [
          {
            "name": "WMUR-TV"
          }
        ],
        "date_published": "2025-10-16T05:21:25.000Z",
        "description_html": "<div><div style=\"left: 0; width: 100%; height: 0; position: relative; padding-bottom: 56.25%;\"><iframe src=\"https://www.youtube.com/embed/_WKdyskvQok\" style=\"border: 0; top: 0; left: 0; width: 100%; height: 100%; position: absolute;\" allowfullscreen scrolling=\"no\" allow=\"encrypted-media\"></iframe></div></div>",
        "description_text": "As President Donald Trump defends his administration's strikes off the coast of Venezuela, he said he has authorized the CIA to explore potential land strike...",
        "thumbnail": "https://i.ytimg.com/vi/_WKdyskvQok/maxresdefault.jpg",
        "title": "Lawmakers concerned about legality of Trump's Venezuela strikes, Shaheen says",
        "url": "https://www.youtube.com/watch?v=_WKdyskvQok"
      },
      {
        "authors": [
          {
            "name": "Reuters"
          }
        ],
        "date_published": "2025-10-16T06:01:43.000Z",
        "description_html": "<div><div style=\"left: 0; width: 100%; height: 0; position: relative; padding-bottom: 56.25%;\"><iframe src=\"https://www.youtube.com/embed/BvBb39Vlggc\" style=\"border: 0; top: 0; left: 0; width: 100%; height: 100%; position: absolute;\" allowfullscreen scrolling=\"no\" allow=\"encrypted-media\"></iframe></div></div>",
        "description_text": "President Donald Trump authorizes CIA covert operations in Venezuela to increase pressure on President Nicolas Maduro's government.#News #Reuters #Newsfeed #...",
        "thumbnail": "https://i.ytimg.com/vi/BvBb39Vlggc/hqdefault.jpg",
        "title": "Trump authorizes CIA operations in Venezuela, raising pressure on Maduro | REUTERS",
        "url": "https://www.youtube.com/watch?v=BvBb39Vlggc"
      },
      {
        "authors": [
          {
            "name": "KTVU FOX 2 San Francisco"
          }
        ],
        "date_published": "2025-10-16T04:55:00.000Z",
        "description_html": "<div><div style=\"left: 0; width: 100%; height: 0; position: relative; padding-bottom: 56.25%;\"><iframe src=\"https://www.youtube.com/embed/jBAbK2hPmUg\" style=\"border: 0; top: 0; left: 0; width: 100%; height: 100%; position: absolute;\" allowfullscreen scrolling=\"no\" allow=\"encrypted-media\"></iframe></div></div>",
        "description_text": "Congress is questioning whether U.S. military attacks on alleged drug boats are legal.Subscribe to KTVU's YouTube channel:https://www.youtube.com/channel/UCV...",
        "thumbnail": "https://i.ytimg.com/vi/jBAbK2hPmUg/maxresdefault.jpg",
        "title": "U.S. military blows up another alleged drug boat off Venezuelan coast",
        "url": "https://www.youtube.com/watch?v=jBAbK2hPmUg"
      }
    ]
  },
  "feed": {
    "description": "",
    "icon": "https://www.youtube.com/s/desktop/d6f8896a/img/favicon_96x96.png",
    "id": "1aXeVKn4hEEZB4DU",
    "is_active": true,
    "rss_feed_url": "https://rss.app/feeds/1aXeVKn4hEEZB4DU.xml",
    "source_url": "https://www.youtube.com/channel/UCYfdidRxbB8Qhf0Nx7ioOYw",
    "title": "News - YouTube"
  },
  "id": "evt_DJkC0kAx2n2q4Cjt",
  "type": "feed_update"
  }'
  

• With API Key in header: curl -X POST '<webhook_url>' -H 'X-Api-Key: <your_api_key>' -H 'Content-Type: application/json' -d '{"id":"evt_1","type":"feed_update","feed":{},"data":{}}'

Tips and Best Practices

• Choose the minimal filter set that captures what you care about; let the plugin ignore the rest upstream.
• Normalize GUID/ID at your notifier side to avoid duplicates.
• If you cannot push directly from RssHub, run a small poller (cron/worker) that converts feed changes into webhook POSTs.
• For unauthenticated mode, prefer allowing only known source IPs or use a secret path segment at your reverse proxy.

Troubleshooting

• No runs: check event type and filters; try removing filters to validate connectivity.
• 401/403 with API Key: ensure the subscription’s API Key matches the header/query you send.
• 400 parse error: ensure Content-Type: application/json or send urlencoded with a payload JSON field.
• Event mismatch: specify the event explicitly (header or query) to avoid heuristic fallback.

Limitations

• This plugin does not create/manage RssHub subscriptions. Configure push from your deployment or a companion worker.
• Only shared-secret style verification is supported; there is no OAuth/HMAC at the moment.