Webhooks

Receive instant notifications when security events occur in CastellanAI.

Built-in Integrations

For Slack and Microsoft Teams, we recommend using our built-in integrations instead of webhooks. See Slack Integration and Teams Integration.

---

What Are Webhooks?

Webhooks send automatic notifications to your systems when important events happen:

System Type	Examples
Ticketing	ServiceNow, Jira, Zendesk
Communication	Slack, Microsoft Teams
Automation	Zapier, Power Automate, custom scripts
SIEM	Splunk, Elastic, QRadar

---

Setting Up Webhooks

1️⃣ Get URL

Step 1: Get Your Webhook URL

First, get the webhook URL from your receiving system:

System	How to Get URL
Slack	Create an Incoming Webhook in workspace settings
ServiceNow	Configure an inbound web service
Jira	Set up a webhook listener or use Jira Automation
Custom	Provide an HTTPS endpoint for POST requests

2️⃣ Create Webhook

Step 2: Create the Webhook in CastellanAI

1. Go to Settings → Webhooks
2. Click + Add Webhook
3. Configure the webhook:

Field	Description
Name	Descriptive name (e.g., "Critical Alerts to ServiceNow")
URL	The webhook URL from your receiving system
Events	Which events should trigger this webhook

3️⃣ Select Events

Step 3: Select Events

Choose which events should trigger notifications:

Event Type	When It Fires
Critical Security Event	Critical severity threat detected
High Security Event	High severity threat detected
Agent Offline	Agent stops reporting
Agent Online	Agent comes back online
Alert Triggered	Custom alert rule matches

4️⃣ Test & Save

Step 4: Test and Save

1. Click Test Webhook to send a test notification
2. Verify the notification was received by your system
3. Click Save to activate the webhook

Test First

Always test webhooks before saving to ensure connectivity and proper formatting.

---

Webhook Payload

📦 Payload Format

Payload Structure

CastellanAI sends JSON payloads to your webhook endpoint:

{
  "event_id": "evt_123456789",
  "event_type": "security_event",
  "severity": "critical",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "title": "Ransomware Detected",
    "description": "Suspicious file activity detected on WORKSTATION-01",
    "host": "WORKSTATION-01",
    "user": "john.doe",
    "source_ip": "192.168.1.100",
    "mitre_tactics": ["execution", "impact"]
  },
  "links": {
    "event_url": "https://app.castellanai.com/events/evt_123456789"
  }
}

📋 Field Reference

Payload Fields

Field	Type	Description
event_id	string	Unique event identifier
event_type	string	Type of event
severity	string	critical, high, medium, low
timestamp	string	ISO 8601 timestamp
data.title	string	Event title
data.description	string	Detailed description
data.host	string	Affected hostname
data.user	string	Associated user
links.event_url	string	Link to event in dashboard

🔑 Headers

Request Headers

CastellanAI includes these headers with webhook requests:

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

Header	Description
X-Castellan-Event	Event type for routing
X-Castellan-Signature	HMAC signature for verification
X-Castellan-Delivery	Unique delivery ID for tracking

---

Managing Webhooks

📊 View Status

View Webhook Status

Go to Settings → Webhooks to see all configured webhooks:

Status	Description
🟢 Active	Working normally
🟡 Warning	Recent delivery failures (will retry)
🔴 Disabled	Disabled due to repeated failures

✏️ Edit

Edit a Webhook

1. Click on the webhook name
2. Make your changes
3. Click Save

Changes take effect immediately for future events.

⏸️ Disable/Delete

Disable or Delete

Action	Effect
Disable	Temporarily stop notifications (keep configuration)
Delete	Permanently remove webhook

Deleted Webhooks

Deleted webhooks cannot be restored. You'll need to recreate the configuration.

---

Delivery & Retries

CastellanAI ensures reliable webhook delivery:

Feature	Description
Delivery Time	Within seconds of event
Retry Attempts	Up to 5 automatic retries
Retry Interval	Exponential backoff (1m, 5m, 15m, 1h, 4h)
Auto-Disable	After 5 consecutive failures
Notification	Email sent when webhook disabled

🔄 Re-enabling a Disabled Webhook

1. Fix the issue with your receiving endpoint
2. Go to Settings → Webhooks
3. Click Enable on the disabled webhook
4. Click Test to verify it's working

---

Best Practices

🔒 Security

Security Best Practices

Practice	Description
Use HTTPS	Only HTTPS URLs accepted
Verify Signatures	Validate X-Castellan-Signature header
Whitelist IPs	Allow CastellanAI IP ranges
Rotate Secrets	Periodically regenerate webhook secrets

🎯 Reliability

Reliability Best Practices

Practice	Description
Monitor Delivery	Check webhook status regularly
Backup Notifications	Use email alerts as backup
Test After Changes	Always test after modifying endpoints
Fast Response	Ensure endpoint responds under 10 seconds

---

Troubleshooting

❌ Not Receiving

Webhook Not Receiving Events

Check	Solution
Webhook status	Verify Active in Settings → Webhooks
Endpoint URL	Confirm URL is correct and accessible
Firewall	Allow connections from CastellanAI
Event filters	Verify selected events match expectations

Quick Test: Click Test to send a test notification.

⏱️ Events Delayed

Events Delayed

Cause	Solution
Processing queue	Check your system's queue
Slow endpoint	Ensure response under 10 seconds
Too many events	Reduce selected event types

🔴 Webhook Disabled

Webhook Disabled

Your webhook was disabled after repeated failures.

Resolution:

1. Check endpoint is working
2. Review error messages in webhook status
3. Fix any identified issues
4. Click Enable then Test

📝 Webhook Setup Checklist

• Obtain webhook URL from receiving system
• Create webhook in CastellanAI
• Select appropriate events
• Test webhook delivery
• Configure signature verification
• Set up backup notification method
• Monitor webhook status regularly

---

What's Next?

Guide	Description
API Access	Enable programmatic access
Slack Integration	Built-in Slack notifications
Teams Integration	Built-in Teams notifications

Need Help?

Contact support@castellanai.com with your webhook configuration details for assistance.