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 — just feedId and timestamp. Article metadata (title, URL, summary, source, etc.) is not delivered in the webhook. Fetch it from the API using feedId.

Rapid changes are debounced

If many items are added to the same feed in a short window, you receive a single webhook for the batch — 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 }
      // Fetch the latest items from the feed — the webhook does not include them.
      const items = await helixApi.listFeedItems(data.feedId, {
        since: data.timestamp,
      });
      await syncNewsItems(items);
    }

    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.