Securing Webhook Endpoints

Built-in SSRF Protection

Server Scout includes robust Server-Side Request Forgery (SSRF) protection through the validateWebhookUrl() function. This security measure automatically blocks webhook URLs that target private IP ranges and potentially dangerous endpoints.

The following IP ranges are blocked by default:

• 10.0.0.0/8 - Private Class A networks
• 172.16.0.0/12 - Private Class B networks
• 192.168.0.0/16 - Private Class C networks
• 127.0.0.0/8 - Loopback addresses (localhost)
• 169.254.0.0/16 - Link-local addresses

Additionally, Server Scout blocks:

• localhost and variations (127.0.0.1, ::1)
• Non-HTTP schemes (only http:// and https:// are permitted)
• URLs that resolve to blocked IP ranges after DNS resolution

Why SSRF Protection Matters

SSRF attacks occur when an attacker manipulates server-side applications to make requests to unintended locations. In the context of webhooks, this could allow malicious users to:

• Scan internal network infrastructure by providing internal IP addresses as webhook endpoints
• Access sensitive services running on localhost (databases, admin panels, configuration APIs)
• Bypass firewalls and access controls by using the monitoring server as a proxy
• Enumerate internal services and gather reconnaissance data

Server Scout's validation prevents these attacks by ensuring webhook requests only target legitimate external endpoints.

Webhook Security Best Practices

Whilst Server Scout handles outbound security, you should implement additional measures on your webhook receiving endpoints:

1. Verify Source IP Addresses

Configure your webhook endpoint to only accept requests from your Server Scout installation's IP address:

# Nginx example
location /webhook {
    allow 203.0.113.10;  # Your Server Scout server IP
    deny all;
    
    proxy_pass http://localhost:3000;
}

2. Use HTTPS Exclusively

Always use HTTPS for webhook URLs to prevent interception:

# Good
https://api.example.com/webhooks/server-scout

# Avoid
http://api.example.com/webhooks/server-scout

3. Implement Webhook Signing

Add a secret token to your webhook URLs and verify it on the receiving end:

import hmac
import hashlib

def verify_webhook_signature(payload, signature, secret):
    expected = hmac.new(
        secret.encode('utf-8'),
        payload.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

4. Rate Limiting

Implement rate limiting to prevent abuse:

# Using fail2ban
[server-scout-webhook]
enabled = true
port = https,http
filter = server-scout-webhook
logpath = /var/log/nginx/access.log
maxretry = 10
bantime = 300

Troubleshooting Webhook Validation Errors

When webhook URLs fail validation, you'll encounter specific error messages. Here's how to resolve common issues:

"URL contains blocked IP range"

Problem: Your webhook URL resolves to a private IP address.

Solution: Ensure your webhook endpoint uses a public IP address or domain name that doesn't resolve to private ranges.

# Check what IP your domain resolves to
nslookup your-webhook-domain.com
dig +short your-webhook-domain.com

"Invalid URL scheme"

Problem: You're using a non-HTTP protocol.

Solution: Change your webhook URL to use http:// or https://:

# Invalid
ftp://example.com/webhook
ws://example.com/webhook

# Valid  
https://example.com/webhook

"Localhost access blocked"

Problem: Your webhook URL targets localhost or loopback addresses.

Solution: Use the external IP address or domain name instead:

# Blocked
http://localhost:3000/webhook
http://127.0.0.1:3000/webhook

# Allowed (if publicly accessible)
http://203.0.113.10:3000/webhook
https://webhooks.yourcompany.com/alerts

Testing Webhook Connectivity

After configuring your webhook URL, test connectivity from your Server Scout server:

# Test HTTP connectivity
curl -I https://your-webhook-endpoint.com/path

# Check DNS resolution
dig +short your-webhook-endpoint.com

# Verify no private IPs in response
nslookup your-webhook-endpoint.com

Remember that webhook validation occurs both when you configure the URL and each time Server Scout attempts to send a notification. This dual-layer approach ensures ongoing security even if DNS records change after initial configuration.