Webhook Integration Guide

What are Webhooks?

Webhooks provide a powerful way to integrate Server Scout with external systems by sending HTTP POST notifications to a URL you specify. When alerts fire, resolve, or send reminders, Server Scout can automatically notify your chosen endpoint with detailed information about the event.

This integration method is particularly useful for connecting to chat platforms like Slack or Discord, ticketing systems, or custom applications that need real-time server monitoring updates.

Configuring Webhooks

Setting up webhook notifications in Server Scout is straightforward:

1. Navigate to Settings → Notifications in your dashboard
2. Click Add Notification Channel
3. Select Webhook as the notification type
4. Enter your target URL in the webhook URL field
5. Optionally, add a description to help identify this webhook later
6. Save the configuration

Once configured, you can assign this webhook to any of your alert rules through the alert configuration interface.

Payload Format

Server Scout sends webhook notifications as JSON POST requests with a standardised payload format. The payload is Slack-compatible by default, making integration with chat platforms seamless.

Example: Alert Fired

{
  "text": "🚨 High CPU usage on web-server-01",
  "color": "danger",
  "server_name": "web-server-01",
  "metric": "CPU Usage",
  "current_value": "92.5",
  "threshold": "80",
  "operator": ">",
  "severity": "critical",
  "status": "fired",
  "timestamp": "2024-01-15T14:30:00Z"
}

Example: Alert Resolved

{
  "text": "✅ CPU usage on web-server-01 has returned to normal",
  "color": "good",
  "server_name": "web-server-01",
  "metric": "CPU Usage",
  "current_value": "45.2",
  "threshold": "80",
  "operator": ">",
  "severity": "critical",
  "status": "resolved",
  "timestamp": "2024-01-15T14:35:00Z"
}

The color field uses standard values: danger for critical alerts, warning for warnings, and good for resolved alerts.

Authentication and Security

When implementing webhook endpoints, follow these security best practices:

Use HTTPS: Always use HTTPS URLs for your webhook endpoints to ensure data is encrypted in transit.

Validate the Source: Consider implementing IP allowlisting or other verification methods to ensure requests originate from Server Scout.

URL Secrets: Add a secret parameter to your webhook URL for additional verification:

https://your-domain.com/webhook?secret=your-random-secret-here

SSRF Protection

Server Scout implements server-side request forgery (SSRF) protection by blocking webhook URLs that point to private IP ranges:

• 10.x.x.x (private networks)
• 172.16.x.x - 172.31.x.x (private networks)
• 192.168.x.x (private networks)
• 127.x.x.x (loopback)
• 169.254.x.x (link-local)

Webhook URLs must point to publicly accessible endpoints. If you need to send notifications to internal systems, consider using a publicly accessible proxy or gateway service.

Retry Behaviour

Webhook delivery follows a simple failure model: if your endpoint returns an HTTP error status code (4xx or 5xx), the notification is logged as failed in Server Scout. Currently, there is no automatic retry mechanism for failed webhook deliveries.

Ensure your webhook endpoints are reliable and return appropriate HTTP status codes (200-299) for successful processing.

Testing Your Webhook

Before relying on webhook notifications for critical alerts, test your configuration:

1. In your webhook notification channel settings, look for the Test button
2. Click Test to send a sample notification
3. Verify the payload arrives at your endpoint correctly
4. Check that your endpoint processes the data as expected

Popular Platform Integration

Slack: Works directly with the Server Scout payload format. Simply use your Slack webhook URL.

Discord: Append /slack to your Discord webhook URL to enable Slack-compatible mode:

https://discord.com/api/webhooks/your-webhook-id/your-token/slack

Microsoft Teams: May require a custom adapter to transform the payload format, as Teams uses a different webhook schema.

PagerDuty: Requires integration through PagerDuty's Events API, which uses a different payload format than the standard webhook output.

For platforms requiring custom payload formats, consider implementing a simple proxy service that receives Server Scout webhooks and transforms them for your target platform.