News Webhooks

Get notified when new news items are added to your feeds.

Event Types

news.item_added

Triggered when a new news item is published and added to your feed.

When Webhooks Send

News webhooks fire immediately when:

• A new article is discovered from any of your configured sources (sites, sitemaps, index pages)
• The article passes through content extraction and processing
• The article is successfully added to your news feed

How Webhooks Send

All news webhooks follow the standard Helix webhook protocol:

• HTTP Method: POST request to your configured endpoint
• Content Type: application/json
• Headers: Includes signature, timestamp, webhook ID, and event ID for verification
• Retry Policy: Failed deliveries are retried with exponential backoff (up to 5 attempts)
• Security: HMAC-SHA256 signature for request verification

See the Webhook Overview for complete details on security verification, retry policy, and HTTP headers.

Payload Structure

{
  "event": "news.item_added",
  "timestamp": "2025-11-08T12:34:56.789Z",
  "data": {
    "item_id": "news_1234567890",
    "title": "Article Title",
    "summary": "Brief summary of the article",
    "url": "https://example.com/article",
    "source": {
      "name": "Example News",
      "domain": "example.com"
    },
    "published_at": "2025-11-08T12:00:00.000Z",
    "categories": ["technology", "business"],
    "relevance_score": 0.92,
    "sentiment": {
      "label": "positive",
      "score": 0.78
    }
  }
}

Filtering

Configure which news items trigger webhooks based on:

• Categories
• Minimum relevance score
• Source domains
• Keywords

Sentiment Labels

• positive - Positive sentiment
• neutral - Neutral sentiment
• negative - Negative sentiment

Example Handler

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

  if (event === 'news.item_added') {
    console.log(`New article: ${data.title}`);
    console.log(`Relevance: ${data.relevance_score * 100}%`);

    // Store or process the news item
    await storeNewsItem(data);
  }

  res.status(200).send('OK');
});