Webhooks — wir melden uns bei Ihnen

Push statt ständig pollen — SpotpriceAPI ruft Ihre URL bei Forecast-/Plan-Updates. Spart Community-Kontingent (120/Tag). Ergänzt Hours Demand und Forecast. Offene REST — jeder HTTP-Client; Loxone meist per Miniserver-HTTP-Out.

Was ist ein Webhook? (Alltag)

Normalerweise fragt Ihr System ständig nach: „Gibt’s was Neues?“ (Polling).

Ein Webhook ist das Gegenteil: Wir rufen Ihre Adresse an, wenn etwas Wichtiges passiert — wie eine SMS „Paket ist da“, statt dass Sie jede Minute beim Paketshop anrufen.

Welche Events gibt es?

Beide nutzen dieselbe Webhook-URL und dasselbe Secret aus dem Portal.

Wann nutzen?

• Sie wollen weniger oft die API pollen
• Ihr Server / Miniserver hat eine öffentliche HTTPS-URL, die wir erreichen können

Hinweis für Loxone-Einsteiger: Webhooks sind fortgeschritten (Port-Freigabe / Cloud). Für den Start reichen Timer + Virtual Output (Pull). Guides: Loxone.

Einrichtung (kurz)

1. Im Portal unter Webhook-Einstellungen HTTPS-URL eintragen 2. Secret notieren 3. Eingehende Requests prüfen (Signatur-Header X-Spotforecast-Signature)

Beispiel-Payload plant.plan_updated

{
  "event": "plant.plan_updated",
  "issued_at": "2026-08-17T18:40:00+02:00",
  "hours_needed": 3,
  "hours_needed_today": 2,
  "energy_charge_kwh": 4,
  "charge_hours_today": [
    { "start": "2026-08-17T19:00:00+02:00", "end": "2026-08-17T20:00:00+02:00" }
  ],
  "prefix_hours_needed_today": 2,
  "prefix_period_hours_today": 10,
  "prefix_energy_charge_kwh": 4,
  "charge_now": 1,
  "charge_stop_soc_pct": 72,
  "discharge_power_kw": 9,
  "discharge_reason": "recharge_planned",
  "adaptive_discharge": true,
  "min_soc_pct": 20,
  "charge_power_kw": 7.9,
  "grid_charge_allowed": true,
  "hours_demand_url": "https://api.spotpriceapi.com/v1/decision/hours-demand",
  "plan_hash": "a1b2c3d4e5f67890"
}

Lesen: Heute noch 2 Stunden / 4 kWh Soll; voller Plan 3 Stunden. EMS-Skalare wie Hours Decide (O1/O2/O9/O11–O13). discharge_power_kw (O12) ist volle Cap, außer Cheap-Hold bei Cover-Lücke, nahe Min-SoC ohne Nachladen, oder Wallbox lädt (ev_charge_block / ev_charge_limit). Ladestunden bleiben bei voller Cap. Ein Wechsel der O12-Cap löst ebenfalls plant.plan_updated aus.

Voller Wochenplan: Das Event enthält nur charge_hours_today (kompakt). Nach jedem plant.plan_updated GET /v1/decision/hours-demand mit mode=decide pullen — Feld day_plan / volle charge_hours. Optional plan_hash (16 Zeichen, SHA-256 der Plan-Starts) zum Dedupe. Materialität prüft intern Today und volle Plan-Starts (morgen-only-Änderungen triggern Push). Reine SOC-Korrektur ohne Slot- oder O12-Änderung (z. B. Cover-Refine v1.9) löst kein Event aus.

Was Webhooks nicht sind

Webhook ist nicht der Weg, um SOC und Zähler zu uns zu schicken. Dafür: Plant Telemetry oder Hours.

Nächste Schritte

• Hours Demand
• Forecast
• Authentifizierung