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"

Webhook Authentication

Webhook callback authentication is separate from the API request authentication used to manage webhooks.

WindBorne generates a signing secret and returns it only when the webhook is created. Store it securely. Every delivery includes Trigger-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(trigger_id, timestamp, raw_body, signature, signing_secret):def verify_webhook(trigger_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 (trigger_id, timestamp, signature, signing_secret)): if not all(isinstance(value, str) for value in (trigger_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"{trigger_id}.{timestamp}.".encode("utf-8") + raw_body signed_content = f"{trigger_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 Trigger-Id values and reject repeats.

Delivery Identifiers

Field	Scope	Description
webhook_id	Webhook	Persistent identifier for the webhook configuration.
subscription_id	Subscription	Persistent identifier for the subscription configuration.
trigger_id	Trigger	Identifier for one subscription firing. It is also sent in the Trigger-Id header and remains the same across retries.

Webhook deliveries do not include a separate delivery-attempt identifier or delivery_id field. Each retry is another attempt for the same trigger and reuses its trigger_id .

Delivery & Retries

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