Troubleshooting Webhook Delivery Failures

When webhook notifications fail to deliver, it can leave you blind to critical server issues. This guide will help you diagnose and resolve common webhook delivery problems in Server Scout.

Testing Your Webhook Configuration

Before diving into troubleshooting, use Server Scout's built-in test feature to verify your webhook setup:

1. Navigate to your notification channel settings
2. Click the Test Channel button
3. Check if the test notification arrives at your endpoint

If the test fails, you'll see an error message that provides clues about the underlying issue.

Common Webhook Delivery Issues

SSRF Validation Errors

Server Scout implements security measures that prevent webhooks from targeting private network ranges. Your webhook will fail if the URL points to:

• 10.x.x.x (private networks)
• 172.16.x.x to 172.31.x.x (private networks)
• 192.168.x.x (local networks)
• 127.x.x.x (localhost)
• 169.254.x.x (link-local addresses)
• localhost or similar local references

Solution: Ensure your webhook URL points to a publicly accessible endpoint. If you're testing locally, use a service like ngrok to create a public tunnel to your development environment.

SSL/TLS Certificate Problems

Server Scout requires valid SSL certificates for HTTPS webhook endpoints. Common certificate issues include:

• Expired certificates
• Self-signed certificates
• Certificate chain problems
• Hostname mismatches

Solution: Verify your endpoint's certificate using tools like SSL Labs' SSL Test or check the certificate details in your browser. Ensure the certificate is valid, trusted, and matches your domain name.

Timeout Errors

Webhook endpoints must respond promptly to avoid timeouts. Server Scout expects responses within a few seconds.

Solution: Optimise your webhook handler to respond quickly. If you need to perform lengthy processing, acknowledge the webhook immediately with a 200 status code, then handle the processing asynchronously.

HTTP Error Responses

Your webhook endpoint might be returning error status codes due to:

• Incorrect HTTP method (Server Scout sends POST requests)
• Missing or incorrect Content-Type handling (expects application/json)
• Authentication or authorisation failures
• Server errors on the receiving end

Solution: Check your endpoint logs and ensure it accepts POST requests with JSON payloads. Return a 200-299 status code to indicate successful receipt.

Authentication Issues

Some webhook services require specific authentication parameters in the URL or headers.

Solution: Review your webhook service's documentation for required authentication parameters. Common requirements include API tokens in the URL query string or specific header values.

Platform-Specific Issues

Slack Webhooks

Slack webhook URLs can expire or become invalidated, especially if workspace settings change.

Solution: If your Slack webhook stops working, generate a new webhook URL:

1. Go to your Slack workspace settings
2. Navigate to Apps → Incoming Webhooks
3. Create a new webhook URL and update your Server Scout configuration

Microsoft Teams

Teams connectors can become inactive due to policy changes or connector expiration.

Solution: Re-create your Teams connector:

1. Remove the existing connector from your Teams channel
2. Add a new "Incoming Webhook" connector
3. Update Server Scout with the new webhook URL

Discord

Discord webhooks require a specific format for compatibility.

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

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

Checking Delivery Status

Server Scout maintains a notification log that shows the delivery status of recent alerts:

1. Access the Notifications or Logs section in your dashboard
2. Review recent notification attempts and their status codes
3. Look for error messages that indicate specific failure reasons

The log will show successful deliveries (200-299 status codes) and failures with detailed error information.

Next Steps

If you've worked through these troubleshooting steps and still experience issues, check Server Scout's status page for any ongoing service disruptions. You can also verify your webhook endpoint independently using tools like curl or Postman to ensure it's responding correctly to POST requests with JSON payloads.

Regular testing of your notification channels ensures you'll receive alerts when they matter most.