Documentation

Webhooks

Webhooks intro

Webhooks let Feed Control push each new feed item to your own application as soon as it's found, so your app doesn't have to poll feeds. This page explains how webhooks work in Feed Control, when they're sent and what you can build with them. It's written for developers: you'll need an endpoint on a server you control, or a service that accepts webhooks.

How webhooks work

A webhook is an HTTP request that one service sends to another when something happens. In Feed Control:

  1. You create a webhook integration that holds the URL of your endpoint.
  2. You connect feeds or bundles to that integration.
  3. Whenever a connected feed finds a new item, Feed Control sends the item to your URL as JSON in an HTTP POST request.
  4. Your endpoint answers with a 2xx status code to confirm it got the item. If it doesn't, Feed Control tries again later.

Every delivery and every retry is recorded, so you can see what was sent and what your endpoint answered. See Testing and delivery history.

Webhooks are a good fit for serverless platforms too: your function only runs when there's something new.

When Feed Control sends a webhook

  • New items only. A webhook goes out when a connected feed finds an item it hasn't seen before, either on its regular check or when you use Fetch Feed Items. Items that were already in the feed when you connected it aren't sent, and later changes to an item don't trigger another webhook.
  • One item per request. If a check finds five new items, your endpoint receives five requests. They can arrive at the same time and in any order.
  • After full-text extraction. If Fetch full text is on for the feed, the item is sent after Feed Control has fetched the article, so the payload includes the full text. If extraction fails, the item is still sent with the content from the source feed. See Full-text extraction.
  • Filtered items are skipped. Items that the feed's filters remove aren't sent. See Filters and curation.
  • Not in curation mode. Feeds in curation mode don't send webhooks, either directly or through a bundle. If you want webhooks for hand-picked items, generate an RSS or JSON feed from the curated feed, add that output as a new feed, and connect the new feed instead.
  • Bundles. When you connect a bundle, you receive new items from every feed in it. The feed object in each request tells you which feed the item came from. If a feed is connected to a webhook directly and also through a bundle connected to the same webhook, you receive its items twice.
  • Only while switched on. Nothing is sent while the feed is inactive, the integration's Active setting is off, or the feed's or bundle's connection is disabled. Items found during that time aren't sent later.

How quickly a webhook arrives depends on how often the feed is checked (Checked every in the feed's settings). Requests go out shortly after a check finds new items.

What's in a webhook

Each request carries one item as a JSON object: its ID, title, URL, author, date, image and GUID, and the content in three forms:

  • content: the content as Feed Control received it (usually HTML)
  • content_clean_html: a cleaned-up, safe-to-display version of that HTML
  • content_plain_text: a plain-text version

A nested feed object describes the feed the item came from. For every field, the headers and an example, see Request and payload reference.

What you can build

  • Save new items to your own database, CMS or spreadsheet.
  • Post items to a chat tool, social account or newsletter system that Feed Control doesn't integrate with directly.
  • Start an automation in a workflow tool that gives you a webhook URL to call.
  • Run a serverless function for each new item, for example to summarise, translate or tag it.

For Slack and Discord you don't need a webhook: Feed Control has built-in integrations. See Integrations overview.

Plans

Plan limits: Plan limits count connections: each feed or bundle connected to an integration is one connection, and only connections that are switched on count. The Basic plan includes one webhook connection (and no Slack or Discord connections). Plus includes up to 10 connections and Business up to 50, shared across webhook, Slack and Discord integrations. The free trial has the same limits as Plus. See Plans and limits.

In this section

← Discord Setting up a webhook →

Can't find what you need? Contact support.