News Webhooks

Get notified when news items are added to your feeds.

Event Types

Event	When it fires	Page
news.item_added	One or more new items added to a news feed	news.item_added

See the per-event-type page for the authoritative data schema. The sections below cover news-specific behavior.

When Webhooks Send

news.item_added fires when:

• New articles are discovered from any of your configured sources (sites, sitemaps, index pages)
• Articles pass content extraction and are added to your news feed

The payload is intentionally minimal — feedId, timestamp, id (news feed item id), and newsPageId. Article metadata (title, URL, summary, source, etc.) is not delivered. Fetch it from GET /feeds/news/{feedId}/items/{id}.

Rapid changes are debounced

Multiple items added to the same feed in a short window collapse to a single webhook per debounce window — not one per item. Always fetch the current feed state from the API; do not assume one webhook = one new item.

How Webhooks Send

News webhooks follow the standard Helix webhook protocol — see the Webhook Overview for envelope shape, security verification, retry policy, and HTTP headers.

Example Handler

import type { Request, Response } from 'express';

app.post('/webhooks/news', async (req: Request, res: Response) => {
  // 1. Verify signature against the RAW body (see Webhook Overview).

  // 2. Acknowledge receipt immediately. Process async.
  res.status(200).send('OK');

  // 3. Use envelope `id` for idempotency — stable across retries.
  const { eventType, id, data } = req.body;
  if (await alreadyProcessed(id)) return;

  try {
    if (eventType === 'news.item_added') {
      // data: { timestamp, feedId, id, newsPageId }
      // `id` is one of possibly several items added during the debounce window.
      // Fetch the named item directly, and reconcile the rest of the feed to
      // catch sibling items collapsed into this webhook.
      const item = await helixApi.getFeedItem(data.feedId, data.id);
      if (item) await upsertNewsItem(item);
      await reconcileFeed(data.feedId);
    }

    await markProcessed(id);
  } catch (err) {
    // Already 200'd — log, don't rethrow. Failed sync is recoverable
    // on the next webhook or a periodic full reconcile.
    console.error('Webhook processing failed', { id, eventType, err });
  }
});

Webhooks are signals, not the source of truth

The news.item_added payload only tells you the feed changed. For article content, always query the API. See Webhook Overview.