Webhooks

Webhooks allow you to receive notifications when events occur in the Helix platform.

Overview

Helix sends HTTP POST requests to your configured webhook endpoints when specific events occur. This allows your application to react to changes without polling.

Webhook Types

We support webhooks for the following event types:

• Fact Checking - Receive notifications when fact-check operations complete
• News - Get notified when new news items are added to your feeds
• Events - Receive updates when new events are published

Configuration

Webhook endpoints can be configured through the Helix dashboard or API. Each webhook requires:

• Endpoint URL - The HTTPS URL where notifications will be sent
• Event Types - Select which events should trigger this webhook
• Secret Key - Used to verify webhook authenticity

HTTP Headers

All webhooks include the following HTTP headers for security and tracking:

Header	Description	Example
Content-Type	Content type of the request	application/json
User-Agent	User agent identifying the webhook sender	Helix-Data-Feeds/1.0
X-Webhook-Signature	HMAC-SHA256 signature for verifying webhook authenticity	v1=a3c8d9e7f2b1a4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9
X-Webhook-Timestamp	Unix timestamp (milliseconds) when the webhook was sent	1704123456789
X-Webhook-ID	Unique identifier for the webhook configuration	123e4567-e89b-12d3-a456-426614174000
X-Webhook-Event-ID	Unique identifier for this specific webhook event	987e6543-e21b-12d3-a456-426614174111

Security & Verification

To verify webhook authenticity, validate the signature in the X-Webhook-Signature header using your webhook secret.

// Example signature verification
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const timestamp = payload.timestamp;
  const signedPayload = timestamp + '.' + JSON.stringify(payload);
  const expectedSignature = 'v1=' +
    crypto
      .createHmac('sha256', secret)
      .update(signedPayload)
      .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Best Practices

• Always verify the signature before processing webhook data
• Check the timestamp to prevent replay attacks (reject requests older than 5 minutes)
• Use HTTPS endpoints only
• Return a 2xx status code promptly to acknowledge receipt

Retry Policy

Failed webhook deliveries are automatically retried with exponential backoff:

• 1st retry: after 1 minute
• 2nd retry: after 5 minutes
• 3rd retry: after 15 minutes
• 4th retry: after 1 hour
• 5th retry: after 6 hours

Webhooks are considered successful on HTTP 2xx responses. Other status codes trigger retries.

After all retries are exhausted, the webhook delivery is marked as failed and you'll need to manually retrieve the missed data via the API.