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

For webhook-related issues or debugging help: 📩 Email: [e-mail] 🌍 Website: https://truthsatellit.space