> For the complete documentation index, see [llms.txt](https://truth-satellite.gitbook.io/truth-satellite/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://truth-satellite.gitbook.io/truth-satellite/docs/webhooks-guide.md).

# Webhooks Guide

### **🔹 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

```http
{
  "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**

```json
{
  "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)**

```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**

```python
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**

```http
GET /alerts
Authorization: Bearer YOUR_API_KEY
```

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

```http
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:** <support@truthsatellit.space>\
🌍 **Website:** <https://truthsatellit.space>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://truth-satellite.gitbook.io/truth-satellite/docs/webhooks-guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.