Webhooks

WindBorne webhooks let you receive real-time HTTP POST notifications as forecast outputs become available. Instead of polling the API, register a webhook URL and configure the subscriptions you care about.

How It Works

You register a webhook with a target URL and one or more subscriptions via POST /webhooks/v1 .
When a subscription matches, WindBorne sends an HTTP POST to your URL with a JSON payload.
Your server responds with a 2xx status to acknowledge receipt.
Failed deliveries are retried with exponential backoff.

Subscription Types

Subscription	Category	Description
initialization_time.available	Forecasts	Sent once every expected forecast hour for a model run is available
forecast_hour.available	Forecasts	Sent as each individual forecast output becomes available

Quick Start

Create a webhook that subscribes to completed WM6 forecast cycles:

curl -X POST -u "$WB_CLIENT_ID:$WB_API_KEY" \curl -X POST -u "$WB_CLIENT_ID:$WB_API_KEY" \

-H "Content-Type: application/json" \ -H "Content-Type: application/json" \

-d '{ -d '{

"url": "https://example.com/webhook", "url": "https://example.com/webhook",

"subscriptions": { "subscriptions": {

"initialization_time.available": { "initialization_time.available": {

"note": "WM6 forecast cycles", "note": "WM6 forecast cycles",

"filters": { "filters": {

"model": "wm-6" "model": "wm-6"

} }

}' \ }' \

"https://api.windbornesystems.com/webhooks/v1" "https://api.windbornesystems.com/webhooks/v1"

Verifying Payloads

WindBorne generates a signing secret and returns it only when the webhook is created. Store it securely. Every delivery includes Webhook-Id , Webhook-Timestamp , and Webhook-Signature headers. Read the unmodified request body as bytes, reject stale timestamps, and verify the HMAC before processing the payload.

import base64import base64

import hashlibimport hashlib

import hmacimport hmac

import timeimport time

MAX_WEBHOOK_AGE_SECONDS = 300MAX_WEBHOOK_AGE_SECONDS = 300

def verify_webhook(event_id, timestamp, raw_body, signature, signing_secret):def verify_webhook(event_id, timestamp, raw_body, signature, signing_secret):

if not isinstance(raw_body, bytes): if not isinstance(raw_body, bytes):

raise TypeError("raw_body must be bytes") raise TypeError("raw_body must be bytes")

if not all(isinstance(value, str) for value in (event_id, timestamp, signature, signing_secret)): if not all(isinstance(value, str) for value in (event_id, timestamp, signature, signing_secret)):

return False return False

try: try:

timestamp_seconds = int(timestamp) timestamp_seconds = int(timestamp)

except (TypeError, ValueError): except (TypeError, ValueError):

return False return False

if abs(time.time() - timestamp_seconds) > MAX_WEBHOOK_AGE_SECONDS: if abs(time.time() - timestamp_seconds) > MAX_WEBHOOK_AGE_SECONDS:

return False return False

signed_content = f"{event_id}.{timestamp}.".encode("utf-8") + raw_body signed_content = f"{event_id}.{timestamp}.".encode("utf-8") + raw_body

expected = "v1," + base64.b64encode( expected = "v1," + base64.b64encode(

hmac.new(signing_secret.encode(), signed_content, hashlib.sha256).digest() hmac.new(signing_secret.encode(), signed_content, hashlib.sha256).digest()

).decode() ).decode()

return hmac.compare_digest(signature, expected) return hmac.compare_digest(signature, expected)

The timestamp check limits replay attempts to five minutes. If duplicate processing within that window matters, also retain recently processed Webhook-Id values and reject repeats.

Delivery & Retries

Return a 2xx response to acknowledge a delivery. Failed deliveries are retried.

API Reference

See the full Webhooks API reference for endpoint details.