Skip to main content

Webhooks

Receive instant notifications when security events occur in CastellanAI.

What Are Webhooks?​

Webhooks send automatic notifications to your systems when important events happen. Instead of constantly checking for updates, CastellanAI pushes alerts directly to your:

  • Ticketing systems (ServiceNow, Jira, Zendesk)
  • Communication platforms (Slack, Microsoft Teams)
  • Automation tools (Zapier, Power Automate, custom scripts)
  • SIEM platforms (Splunk, Elastic, QRadar)
tip

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

Setting Up Webhooks​

Step 1: Get Your Webhook URL​

First, get the webhook URL from your receiving system:

  • Slack: Create an Incoming Webhook in your Slack workspace
  • ServiceNow: Configure an inbound web service
  • Jira: Set up a webhook listener or use Jira Automation
  • Custom system: Provide an HTTPS endpoint that can receive POST requests

Step 2: Create the Webhook in CastellanAI​

  1. Go to Settings → Webhooks
  2. Click + Add Webhook
  3. Configure the webhook:
FieldDescription
NameA descriptive name (e.g., "Critical Alerts to ServiceNow")
URLThe webhook URL from your receiving system
EventsWhich events should trigger this webhook

Step 3: Select Events​

Choose which events should trigger notifications:

Event TypeWhen It Fires
Critical Security EventA critical severity threat is detected
High Security EventA high severity threat is detected
Agent OfflineAn agent stops reporting
Agent OnlineAn agent comes back online
Alert TriggeredA custom alert rule matches

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

Managing Webhooks​

View Webhook Status​

Go to Settings → Webhooks to see all configured webhooks:

  • Active: Webhook is working normally
  • Warning: Recent delivery failures (will retry automatically)
  • Disabled: Webhook has been disabled due to repeated failures

Edit a Webhook​

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

Disable or Delete​

  • Disable: Temporarily stop notifications without losing configuration
  • Delete: Permanently remove the webhook

Delivery and Retries​

CastellanAI ensures reliable webhook delivery:

  • Webhooks are delivered within seconds of an event occurring
  • If delivery fails, we retry automatically (up to 5 attempts)
  • After 5 failures, the webhook is automatically disabled
  • You'll receive an email notification if a webhook is disabled

To re-enable 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​

  • Use HTTPS: Only HTTPS URLs are accepted for security
  • Monitor delivery: Check webhook status regularly in Settings
  • Set up backup notifications: Use email alerts as a backup for critical events
  • Test after changes: Always test webhooks after modifying your receiving system

Troubleshooting​

Webhook Not Receiving Events​

  1. Check the webhook status in Settings → Webhooks
  2. Verify your endpoint URL is correct and accessible
  3. Ensure your firewall allows connections from CastellanAI
  4. Click Test to send a test notification

Events Delayed​

  • Check your system's processing queue
  • Verify your endpoint responds quickly (under 10 seconds)
  • Review your event filters—you may have too many events selected

Webhook Disabled​

Your webhook was disabled after repeated failures. To fix:

  1. Check your endpoint is working
  2. Review any error messages shown in the webhook status
  3. Click Enable and then Test

Need help? Contact support@castellanai.com with your webhook configuration details.