Webhooks

Get notified when things happen. Costs, errors, thresholds.

Create a webhook

curl -X POST http://localhost:4200/api/webhooks \
  -d '{
    "name": "slack-alerts",
    "url": "https://hooks.slack.com/services/T.../B.../xxx",
    "events": ["cost_threshold", "provider_error", "rate_limit_hit"],
    "enabled": true
  }'

Available events

cost_threshold fires when daily or monthly spend exceeds a configured limit. Set thresholds via the API or config file.

provider_error fires when a provider returns a 5xx error or times out. Useful for early detection of provider outages.

rate_limit_hit fires when a user or team hits their rate limit. Helps identify users who need higher limits or are misconfigured.

circuit_open fires when the failover circuit breaker opens for a provider. Indicates a provider is having sustained issues.

trust_violation fires when a request violates a Brand audit policy. Compliance teams can use this for real-time alerting.

Webhook payload

Webhooks send a JSON POST with this structure:

{
  "event": "cost_threshold",
  "timestamp": "2026-03-31T10:30:00Z",
  "data": {
    "threshold_usd": 50.00,
    "current_usd": 52.30,
    "period": "daily"
  }
}

Built-in integrations

Stockyard includes pre-built templates for Slack, Discord, and PagerDuty. These format the webhook payload into native message formats so alerts look clean in your notification channels.

Retry behavior

Failed webhook deliveries are retried 3 times with exponential backoff (5s, 30s, 5m). After 3 failures, the webhook is marked as failing and you will see a warning in the dashboard.