Custom Webhooks

Send CastellanAI security events to external systems like SIEM platforms, ticketing systems, or automation tools.

Built-in Integrations First

Most users don't need custom webhooks. Use the built-in integrations for Microsoft Teams or Slack instead.

---

What Are Webhooks?

Webhooks automatically push security events to other systems in real-time.

---

Who Should Use Webhooks?

Use Case	Example
SIEM Integration	Send events to Splunk, QRadar, or Elastic
Ticketing Automation	Create Jira or ServiceNow tickets automatically
Custom Dashboards	Feed events to internal security dashboards
Workflow Automation	Trigger actions in Zapier or Power Automate

---

Setting Up a Webhook

1️⃣ Navigate

Step 1: Navigate to Webhook Settings

1. Log in to the CastellanAI Portal
2. Go to Configuration → Notifications
3. Click + Add Channel
4. Select Custom Webhook

2️⃣ Configure

Step 2: Configure Your Webhook

Field	Description	Example
Name	Descriptive name	"Splunk SIEM Feed"
Endpoint URL	HTTPS URL of your system	https://splunk.company.com/webhook
Authentication	API key or token	Your system's API key

HTTPS Required

HTTP endpoints are not supported for security reasons.

3️⃣ Event Types

Step 3: Choose Event Types

Option	What Gets Sent
All Events	Every security event detected
High Severity Only	Critical and High severity events
Specific Types	Only selected categories (malware, auth, etc.)

4️⃣ Test

Step 4: Test the Connection

1. Click Send Test to verify your webhook
2. Check that your receiving system received the test event
3. If test fails, verify endpoint URL and authentication

5️⃣ Activate

Step 5: Activate

Click Save and Enable to start sending events to your webhook.

---

Webhook Payload

📦 Payload Format

JSON Payload Structure

{
  "event_id": "evt_123456789",
  "event_type": "malware_detection",
  "severity": "critical",
  "timestamp": "2025-01-15T10:30:00Z",
  "device": "WORKSTATION-01",
  "user": "john.doe",
  "description": "Ransomware detected on endpoint",
  "risk_score": 95,
  "mitre_tactics": ["execution", "impact"],
  "source_ip": "192.168.1.100"
}

📋 Field Reference

Payload Fields

Field	Description
event_id	Unique identifier
event_type	Category (malware, authentication, etc.)
severity	Critical, High, Medium, or Low
timestamp	When the event occurred
device	Affected hostname
user	Associated username
description	Event details
risk_score	Numerical severity (0-100)

🔑 Headers

Request Headers

Content-Type: application/json
X-Castellan-Event: malware_detection
X-Castellan-Signature: sha256=abc123...
X-Castellan-Delivery: del_987654321

---

Authentication Options

🔑 API Key

API Key Authentication

Include API key in request header:

Header	Value
Authorization	Bearer YOUR_API_KEY
X-API-Key	YOUR_API_KEY

👤 Basic Auth

Basic Authentication

Setting	Value
Username	Your service account
Password	Your API password

Sent as base64-encoded Authorization: Basic header.

⚙️ Custom Headers

Custom Headers

Add any custom headers your system requires:

Header	Example
X-Custom-Token	your-token
X-Org-ID	org-123

---

Monitoring Webhook Status

📊 Status

Delivery Status

Status	Meaning
✅ Success	Event delivered successfully
🔄 Retrying	Delivery failed, retry in progress
❌ Failed	Delivery failed after all retries

📜 Delivery Logs

View Delivery Logs

1. Go to Configuration → Notifications
2. Click on your webhook
3. View the Delivery Log tab

Logs show:

• Timestamp
• Event type
• HTTP response code
• Error messages (if any)

Auto-Disable

Webhooks with more than 80% failure rate over 24 hours are automatically disabled. Fix the endpoint issue, then re-enable.

---

Troubleshooting

❌ Not Receiving

Webhook Not Receiving Events

Check	Solution
Webhook enabled	Toggle should be green
Event filters	Verify filters match expected events
Delivery log	Check for error messages

🔐 Auth Errors

Authentication Errors

Check	Solution
API key correct	Verify key hasn't changed
Key not expired	Check expiration date
Header format	Ensure format matches expectations

⏱️ Events Delayed

Events Delayed or Missing

Check	Solution
Rate limiting	Your endpoint may be throttling
Event volume	Verify system can handle load
Network issues	Check connectivity

📝 Webhook Setup Checklist

• Identify receiving system requirements
• Determine authentication method
• Create webhook in CastellanAI
• Configure event filters
• Test webhook delivery
• Verify payload format
• Monitor delivery status
• Set up alerting for failures

---

What's Next?

Guide	Description
Email Alerts	Set up email notifications
Microsoft Teams	Built-in Teams integration
Slack	Built-in Slack integration

Need Help?

Enterprise customers: Contact your Technical Account Manager All customers: Email support@castellanai.com with integration requirements