Webhooks

Solwyn delivers project notifications to your own HTTPS endpoint as signed JSON payloads. Use webhooks to react to budget thresholds in your own paging stack, forward events into a data warehouse, or wire spend alerts into automation you already run.

When to use webhooks

Webhooks are the right surface when:

• You want to receive Solwyn events in your own infrastructure (not just via Slack, PagerDuty, SMS, or email).
• You need to react programmatically to a budget threshold, budget-exceeded, or circuit-breaker event. (Provider-outage events are reserved in the contract, not yet delivered.)
• You already have an HTTP service that can verify signatures and process JSON.

If you only want a notification channel for humans, the dashboard's built-in Slack, PagerDuty, SMS, and email integrations are usually faster to set up.

Setup

Webhooks require a paid plan — Founder and above. The Free tier has no webhook targets and delivers budget events to email only; if an account downgrades to Free, any webhook target left behind stops delivering immediately. See Plans & billing.

1. Open the project's Settings → Webhooks page in the dashboard.
2. Add a webhook target with an HTTPS URL and an event filter (* for all events, or a comma-separated list — see Events).
3. Solwyn shows the signing secret once at creation. Copy it into your secret store immediately — it is never retrievable again.
4. Implement an endpoint that verifies the X-Solwyn-Signature header and processes the JSON payload.

Payload shape

Every delivery is a POST with Content-Type: application/json and this body:

{
  "event_type": "budget_threshold",
  "project_id": "proj_a1b2c3d4e5f6a7b8c9d0e1f2",
  "timestamp": "2026-05-05T18:00:00.123456+00:00",
  "idempotency_key": "notification:7f3a9d2c815e4b6f0a1d8c3e5b7f9a2d4c6e8b0f1a3d5c7e9b2f4a6c8e0d1b3f",
  "data": {
    "project_name": "production",
    "budget_limit": 100.0,
    "current_usage": 80.5,
    "threshold_pct": 80,
    "period": "monthly",
    "period_date": "2026-05",
    "channels": ["webhook"]
  }
}

The body is signed exactly as transmitted — verify against the raw bytes, not against re-serialized JSON. See Verifying signatures.

Delivery semantics

• Transport: HTTPS only. URLs targeting localhost, private IP space, link-local addresses, or cloud metadata endpoints (e.g. 169.254.169.254) are rejected at creation time.
• Retries: Up to 3 attempts per event, with exponential backoff (no delay before the first attempt, then 1 s, then 2 s).
• Idempotency: Every delivery carries an Idempotency-Key request header matching the payload's idempotency_key. It is stable across retries and redeliveries of the same event, so you can dedupe on it directly.
• Timeout: 5 seconds per attempt. Slow endpoints will see retries even if the event eventually lands.
• Success: Any 2xx response status. Non-2xx (or any transport error) triggers the next retry.
• No dead-letter queue: After 3 failed attempts the event is dropped. Treat webhook delivery as at-most-once — for anything you cannot afford to miss, also subscribe via a second channel (email, Slack) or query the dashboard's cost data to reconcile.
• No redirects: Solwyn does not follow 3xx responses. Configure your endpoint at the final URL.

Event filtering

Each webhook target stores its own event filter as a comma-separated list:

• * (default) — deliver every event type.
• budget_threshold,budget_exceeded — deliver only the named types.

Filtering happens on Solwyn's side, so your endpoint will only receive the event types you opted in to.

Rotating the signing secret

Rotate a webhook's signing secret from the dashboard at any time:

• The new secret is shown once in the rotation response.
• The old secret is immediately invalid — there is no overlap window.
• Plan for a brief outage during rotation, or stage the new secret in your endpoint before triggering the rotation.

Next steps

• Verifying signatures — Python and Node.js recipes, plus the pitfalls that pass tests but break in production.
• Events — every event type Solwyn can emit, with per-type payload shape.