Configuring webhooks

Feature Availability

Webhooks are available exclusively to Pro and Enterprise plan subscribers. They allow you to integrate SSHwatch alerts with your existing security and monitoring tools.

Understanding Webhooks

What Are Webhooks?

Webhooks are real-time HTTP notifications that are automatically sent to your designated endpoint whenever SSH events matching your predefined alert rules occur. This powerful mechanism enables seamless automation and integration with other systems in your infrastructure, allowing for immediate responses to important events. Each webhook delivers comprehensive event information in JSON format, making it straightforward to parse and act upon the data within your applications or security workflows.

Common Use Cases

Common use cases for webhooks include integration with communication platforms like Slack or Discord to alert team members, feeding critical data to security information systems for threat analysis, triggering automated responses to potential security incidents, centralizing logs across multiple tools for comprehensive monitoring, and building custom notification systems tailored to your organization's specific needs and workflows.

Setting Up Webhooks

Configuration Steps

1. Navigate to Settings
   • Click your email address in top right
   • Choose "Webhooks" tab
2. Add Webhook URL
   • Enter your endpoint URL
   • Must be a valid HTTPS URL
   • Should accept POST requests
   • Must respond within timeout period
3. Save Configuration
   • Click "Save Webhook"
   • System will verify endpoint
   • Confirmation message appears when saved

Webhook Requirements

Your endpoint must:

• Accept HTTPS POST requests
• Return 2xx status code
• Process JSON payloads
• Handle requests within 10 seconds
• Be publicly accessible

Using Webhooks

Alert Integration

• Select "Webhook only" or "Email and Webhook" when creating alerts
• All matching events trigger webhook calls
• Multiple alerts can use same webhook
• Webhook delivery is asynchronous

Example payload Format

{
    "event_type": "ssh_login_attempt",
    "timestamp": "2025-02-24T15:30:22Z",
    "server_id": "web-server-01",
    "ip_address": "192.168.1.1",
    "username": "admin",
    "success": false,
    "security_rating": "HIGH_RISK",
    "risk_score": 85,
    "risk_reasons": ["Multiple failed attempts", "Unknown IP"],
    "alert_rule": {
        "id": 123,
        "field": "login_user",
        "condition": "equals",
        "value": "root"
    }
}