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.

From Subscription to Delivery

Create a webhook with your server's URL and the subscriptions you need. You can add subscriptions later.

WeatherMesh6 0Z and 12Z with gridded forecasts returned

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",
"initialization_time_hours": ["0:00", "12:00"] "initialization_time_hours": ["0:00", "12:00"]
}, },
"response_options": { "response_options": {
"type": "gridded" "type": "gridded"
} }
} }
} }
}' \ }' \
"https://api.windbornesystems.com/webhooks/v1" "https://api.windbornesystems.com/webhooks/v1"
When a subscription is triggered, WindBorne sends an HTTP POST to your URL with a JSON payload. You can also include API responses in the payload.
Your server verifies the webhook signature and returns a 2xx status to acknowledge receipt.
If an automatic delivery fails, WindBorne retries up to three times with increasing delays.

Subscription Types

Choose the subscriptions that match the updates you want to receive. Each subscription's reference page describes when it is triggered and its available filters and response options. Each webhook can contain at most one subscription of each type.

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
degree_days.available	Forecasts	Sent when a degree day calculation becomes available for a model run
tropical_cyclones.available	Forecasts	Sent when a tropical cyclone calculation becomes available
events.available	Forecasts	Sent when atmospheric river, heatwave, coldwave, or front products are published for a model run

Attaching Forecast Responses

Use response_options to include an API response in the webhook payload when a subscription is triggered. WindBorne prepares the response using the forecast that triggered the subscription and includes it in data.response .

The available response options depend on the subscription type. See the reference pages for gridded forecasts, interpolated point forecasts, tropical cyclones, and degree days for configuration details.

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	Identifies the update that triggered the notification, such as a forecast cycle becoming available; a test ping uses a new identifier.

Webhook deliveries do not include a separate delivery-attempt identifier or delivery_id field. Use subscription_id and trigger_id together to identify one logical notification. Each retry is another attempt for that notification and reuses both its trigger_id and subscription_id .

Delivery & Retries

Return a 2xx response to acknowledge a delivery. Failed automatic deliveries are retried up to three times with increasing delays. A ping makes one immediate delivery attempt and returns an error without scheduling retries.

Webhook Authentication

The secret is only created once for you. Store it securely, as it is used to authenticate webhook callbacks separately from the API request authentication used to manage webhooks.

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.

Check that a webhook came from WindBorne and hasn't been altered

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. To avoid processing the same update twice for a subscription, keep track of recently processed Trigger-Id and subscription_id pairs and skip any pair you have already processed.