Webhooks Guide

Truth Satellite supports real-time webhooks that notify users when classified intelligence matches their predefined criteria. This guide explains how to set up, configure, and manage webhook notificat

🔹 What Are Webhooks?

Webhooks allow your systems to receive real-time alerts when intelligence reports meet specific conditions. Instead of constantly polling the API, your server will receive instant updates whenever relevant intelligence data becomes available.

🚨 Example Use Cases: ✔ Get notified about insider trading alerts before market movements. ✔ Track diplomatic meetings between high-profile figures. ✔ Monitor classified financial transactions and offshore movements.

🔹 Setting Up a Webhook Subscription

To receive webhook notifications, send a POST request to the /alerts endpoint.

🚨 Code Example: Subscribing to a Webhook

POST /alerts Authorization: Bearer YOUR_API_KEY Content-Type: application/json

{
  "event": "insider_trade",
  "callback_url": "https://yourserver.com/webhook",
  "keywords": ["offshore", "stock drop"],
  "priority_level": "high"
}

Required Parameters:

Parameter

Type

Required

Description

event

string

✅ Yes

Type of intelligence event to track.

callback_url

string

✅ Yes

Your server's endpoint to receive webhook data.

keywords

array

❌ No

List of keywords to filter intelligence reports.

priority_level

string

❌ No

"high", "medium", or "low" (default: "medium").

🔹 Receiving Webhook Events

When an intelligence event matches your filter, Truth Satellite sends a POST request to your callback_url.

🚨 Code Example: Webhook Payload Example

{
  "event": "insider_trade",
  "category": "finance",
  "source": "classified",
  "content": "CEO of XYZ Corp moved $500M offshore before stock drop.",
  "timestamp": "2025-02-08T14:00:00Z"
}

🔹 Verifying Webhook Authenticity

To ensure that the webhook data is from Truth Satellite, verify the HMAC-SHA256 signature included in the request headers.

🚨 Code Example: Verifying Webhook Signature (Python)

import hashlib
import hmac

SECRET_KEY = b"your_secret_key"

def verify_signature(payload, received_signature):
    signature = hmac.new(SECRET_KEY, payload.encode(), hashlib.sha256).hexdigest()
    return signature == received_signature

Webhook Headers:

Header

Description

X-TruthSatellite-Signature

HMAC-SHA256 signature for verifying authenticity.

X-TruthSatellite-Timestamp

Timestamp of the request.

🔹 Handling Webhook Responses

Your server must respond with HTTP 200 OK to confirm successful receipt of the webhook.

🚨 Code Example: Handling Webhook in Python Flask Server

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route("/webhook", methods=["POST"])
def receive_webhook():
    data = request.json
    print("Received Webhook:", data)
    return jsonify({"status": "success"}), 200

if __name__ == "__main__":
    app.run(port=5000)

If the server does not respond within 5 seconds, the webhook will be retried up to 3 times.

🔹 Managing Webhook Subscriptions

To list all active webhooks: 🚨 Code Example: Fetching Active Webhooks

GET /alerts
Authorization: Bearer YOUR_API_KEY

To delete a webhook subscription: 🚨 Code Example: Removing a Webhook Subscription

DELETE /alerts
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json  

{
  "event": "insider_trade",
  "callback_url": "https://yourserver.com/webhook"
}

🔹 Webhook Best Practices

✔ Validate the Signature – Always verify webhook authenticity. ✔ Use HTTPS for Webhooks – Ensure all communication is encrypted. ✔ Respond Quickly – Acknowledge receipt within 5 seconds. ✔ Log Webhook Events – Keep track of all received payloads for debugging.

🔹 Contact & Support

PreviousCode of Conduct NextAPI Reference

Last updated 3 months ago

import hashlib import hmac SECRET_KEY = b"your_secret_key" def verify_signature(payload, received_signature): signature = hmac.new(SECRET_KEY, payload.encode(), hashlib.sha256).hexdigest() return signature == received_signature

from flask import Flask, request, jsonify app = Flask(__name__) @app.route("/webhook", methods=["POST"]) def receive_webhook(): data = request.json print("Received Webhook:", data) return jsonify({"status": "success"}), 200 if __name__ == "__main__": app.run(port=5000)