Custom Webhooks

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

What Are Webhooks?

Webhooks automatically push security events to other systems in real-time. When something happens in CastellanAI (like a threat detection), your external system receives an instant notification with event details.

tip

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

Who Should Use Webhooks?

Webhooks are designed for organizations that need to:

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

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

Step 2: Configure Your Webhook

Enter the following information:

The webhook configuration form with fields for Name, Endpoint URL, and Authentication.

Field	Description	Example
Name	A descriptive name for this webhook	"Splunk SIEM Feed"
Endpoint URL	The HTTPS URL of your receiving system	https://splunk.company.com/webhook
Authentication	API key or token if required	Your system's API key

warning

HTTPS is required. HTTP endpoints are not supported for security reasons.

Step 3: Choose Event Types

Select which events should be sent to this webhook:

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

Step 4: Test the Connection

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

Step 5: Activate

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

What Information Is Sent?

Each webhook includes details about the security event:

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)

Monitoring Webhook Status

Check if your webhooks are working properly:

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

The webhook delivery log showing recent deliveries with Success, Retrying, and Failed status indicators.

Status	Meaning
✓ Success	Event delivered successfully
⟳ Retrying	Delivery failed, retry in progress
✗ Failed	Delivery failed after all retries

warning

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

Troubleshooting Webhooks

Webhook Not Receiving Events

1. Check the webhook is enabled (toggle should be green)
2. Verify event filters match the events you expect
3. Check the delivery log for error messages

Authentication Errors

1. Verify your API key or token is correct
2. Check the key hasn't expired
3. Ensure the authentication header format matches what your system expects

Events Delayed or Missing

1. Check your endpoint isn't rate-limiting requests
2. Verify your system can handle the event volume
3. Check for network issues between CastellanAI and your endpoint

Getting Help

If you need assistance setting up webhooks with specific platforms:

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

What's Next?

• Email Alerts - Set up email notifications
• Microsoft Teams - Use built-in Teams integration
• Slack - Use built-in Slack integration