Webhooks

Webhooks deliver real-time notifications when events occur in the Cliff Horizon system. Subscribe to the events you need and receive HTTP POST requests to your endpoint.

API specifications are preliminary and subject to change during development. This documentation represents the planned API design.

Event Types

Event	Description	Typical Use
`forecast.updated`	New calibrated forecast available	Dashboard refresh, downstream model update
`alert.triggered`	Probability crossed a configured threshold	Operational decision-making
`alert.cleared`	Probability dropped back below threshold	Stand-down notification
`policy.created`	New derivative policy activated	Accounting, risk register
`policy.trigger_approaching`	Oracle data approaching trigger threshold	Early warning
`policy.settled`	Policy resolved — payout or expiry	Settlement confirmation
`calibration.drift`	Calibration metrics degraded beyond threshold	Engine health monitoring

Webhook Payload

All webhooks follow the same envelope format:

{
  "id": "evt_abc123",
  "type": "alert.triggered",
  "created_at": "2026-04-04T14:30:00Z",
  "data": {
    "alert_id": "alt_xyz789",
    "project_id": "prj_def456",
    "variable": "rainfall",
    "threshold": 50,
    "current_probability": 0.65,
    "previous_probability": 0.58,
    "location": {
      "lat": -6.2088,
      "lon": 106.8456,
      "name": "Jakarta"
    }
  }
}

Webhook Security

Verify webhook authenticity using the signature header:

X-CliffHorizon-Signature: sha256=xxxxxxxxxxxxxxxxxxxxxxxx

Compute HMAC-SHA256 of the raw request body using your webhook secret key. Compare against the signature header.

import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

Configuration

Configure webhooks via the dashboard settings or API:

curl -X POST -H "Authorization: Bearer ch_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/cliff-horizon",
    "events": ["alert.triggered", "alert.cleared", "policy.settled"],
    "secret": "your_webhook_secret"
  }' \
  https://api.cliffhorizon.com/v1/webhooks

Retry Policy

Failed deliveries (non-2xx response) are retried with exponential backoff:

Attempt	Delay
1	Immediate
2	1 minute
3	5 minutes
4	30 minutes
5	2 hours
6	12 hours

After 6 failed attempts, the webhook is marked as failing and an email notification is sent to the account owner.