Fact Checking Webhooks

Receive notifications when fact-check operations complete or change status.

Event Types

fact_check.completed

Triggered when a fact-check operation has finished processing successfully.

fact_check.failed

Triggered when a fact-check operation fails during processing.

fact_check.status_changed

Triggered when a fact-check status changes during the verification workflow.

When Webhooks Send

Fact-checking webhooks fire when:

• Completed: Fact-check finishes successfully with verdict and confidence score
• Failed: Processing fails due to errors, invalid sources, or system issues
• Status Changed: Status transitions during the verification workflow (e.g., pending → processing → completed)

Webhooks are sent when the status change occurs.

How Webhooks Send

All fact-checking 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

fact_check.completed Payload

{
  "event": "fact_check.completed",
  "timestamp": "2025-11-08T12:34:56.789Z",
  "data": {
    "fact_check_id": "fc_1234567890",
    "status": "completed",
    "claim": "The original claim text",
    "verdict": "mostly_true",
    "confidence": 0.85,
    "sources": [
      {
        "url": "https://example.com/source1",
        "title": "Source Title",
        "relevance": 0.92
      }
    ],
    "completed_at": "2025-11-08T12:34:56.789Z"
  }
}

Verdict Types

• true - Claim is verified as accurate
• mostly_true - Claim is largely accurate with minor inaccuracies
• mixed - Claim contains both accurate and inaccurate elements
• mostly_false - Claim is largely inaccurate
• false - Claim is verified as false
• unverifiable - Insufficient information to verify

Example Handler

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

  switch (event) {
    case 'fact_check.completed':
      console.log(`Fact check ${data.fact_check_id} completed`);
      console.log(`Verdict: ${data.verdict} (${data.confidence * 100}%)`);
      await processFactCheck(data);
      break;

    case 'fact_check.failed':
      console.log(`Fact check ${data.fact_check_id} failed`);
      console.log(`Error: ${data.error}`);
      await handleFactCheckFailure(data);
      break;

    case 'fact_check.status_changed':
      console.log(`Fact check ${data.fact_check_id} status: ${data.status}`);
      await updateFactCheckStatus(data);
      break;
  }

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