checkId: check.integration.webhooks plugin: stellaops.doctor.integration severity: warn tags: [integration, webhooks, notifications, events]

Integration Webhook Health

This Doctor check gives operators and DevOps engineers a fleet-wide view of every configured webhook endpoint: whether outbound targets are reachable and whether delivery failure rates are trending toward trouble. It complements the channel-specific Slack and Teams checks with a single health signal across all event integrations.

What It Checks

Iterates over all webhook endpoints defined under Webhooks:Endpoints. For outbound webhooks it sends an HTTP HEAD request to the target URL and considers the endpoint reachable if the response status code is below 500. For inbound webhooks it marks reachability as true (endpoint is local). It then calculates the delivery failure rate from TotalDeliveries and SuccessfulDeliveries counters. The check fails if any outbound endpoint is unreachable or if any webhook’s failure rate exceeds 20%, warns if any webhook’s failure rate is between 5% and 20%, and passes otherwise.

Why It Matters

Webhooks are the primary event-driven communication channel between Stella Ops and external systems. Unreachable outbound endpoints mean notifications, CI triggers, and audit event deliveries silently fail. A rising failure rate is an early warning of endpoint degradation that can cascade into missed alerts, delayed approvals, and incomplete audit trails.

Common Causes

How to Fix

Docker Compose

# List configured webhooks
grep 'WEBHOOKS__' .env

# Test an outbound webhook endpoint
docker compose exec gateway curl -I https://hooks.example.com/stellaops

# View webhook delivery logs
docker compose logs platform | grep -i webhook

# Update a webhook URL
echo 'Webhooks__Endpoints__0__Url=https://hooks.example.com/v2/stellaops' >> .env
docker compose restart platform

Bare Metal / systemd

# Check webhook configuration
cat /etc/stellaops/appsettings.Production.json | jq '.Webhooks'

# Test endpoint connectivity
curl -I https://hooks.example.com/stellaops

# Review delivery history
stella webhooks logs <webhook-name> --status failed

# Retry failed deliveries
stella webhooks retry <webhook-name>

Kubernetes / Helm

# values.yaml
webhooks:
  endpoints:
    - name: slack-releases
      url: https://hooks.example.com/stellaops
      direction: outbound

helm upgrade stellaops ./chart -f values.yaml

Verification

stella doctor run --check check.integration.webhooks