Webhooks

Xweather Webhooks

Xweather pushes data sets to an HTTPS endpoint you own, instead of your application polling data.api.xweather.com on a timer. The payload is byte-for-byte the same shape the Weather API returns, so existing response-parsing code is reusable with almost no change.

Webhooks are a premium add-on requiring a separate subscription, and endpoints are registered by Xweather staff — not self-service. There is no API call or dashboard toggle that turns this on. Say so early: the work splits into what the user can build today (the receiver) and what needs a conversation with their account executive (the subscription and registration).

When webhooks are the right answer

Reach for them when the user is polling frequently for data that changes unpredictably — lightning strikes, hail threats, new alerts, storm cell updates. Polling that on a short interval burns accesses continuously and still adds latency; push removes both problems.

Polling via the weather-api skill stays the better fit when the data is requested on demand (a user opens a page), when the update cadence is slow and predictable (daily normals, hourly temperatures), or when the user can't host a public HTTPS endpoint.

How a delivery works

Xweather sends an HTTP POST to the registered URL.

The endpoint must answer with a 2xx status — 202 is the conventional choice — and do it immediately. The response body is ignored.

Acknowledge first, process second. Any real work belongs in a background job, queue, or thread started after the status is written. A handler that parses, matches polygons, and sends notifications before responding will eventually exceed the delivery timeout, and a timeout is treated as a failed delivery.

Retries

A non-2xx status or a connection timeout triggers a retry, typically no more than two or three attempts. After that the delivery is marked failed and is not attempted again — the next opportunity is the next update for that data set. There is no replay or backfill mechanism, so a receiver that's down during an event has permanently missed it. Two consequences worth raising:

• Deliveries are effectively at-most-once after retries are exhausted. If gapless history matters, pair the webhook with a periodic API query as a reconciliation backstop.
• Handlers should be idempotent, because a retry can duplicate a delivery your server actually did process but was too slow to acknowledge. Key writes on a stable field — station id, alert id, strike timestamp — and upsert rather than insert.

Available data sets

Common:

Also available, less commonly used: Air Quality · Earthquakes · Observations · Rivers · Storm Reports · Storm Cells.

Anything outside both lists needs a support conversation. Each data set corresponds to a Weather API endpoint. Use the weather-api skill when you need the endpoint's response-field reference.

Building the receiver

The whole contract is: accept POST, verify the secret, return 202, process asynchronously.

import express from 'express';
const app = express();
app.use(express.json());

app.post('/webhooks/xweather/a3f8c2d1e5b7', (req, res) => {
  if (req.get('x-api-key') !== process.env.XWEATHER_WEBHOOK_KEY) {
    return res.status(401).end();
  }
  res.status(202).end();        // acknowledge first
  enqueue(req.body);            // then hand off — never process inline
});

app.listen(3000);

from flask import Flask, request, abort
import os, threading

app = Flask(__name__)

@app.route('/webhooks/xweather/a3f8c2d1e5b7', methods=['POST'])
def receive_webhook():
    if request.headers.get('X-Api-Key') != os.environ['XWEATHER_WEBHOOK_KEY']:
        abort(401)
    data = request.get_json()
    threading.Thread(target=process_payload, args=(data,)).start()
    return '', 202

The docs' own examples use a bare threading.Thread and an unguarded handler. That's fine as an illustration, but for anything real prefer a durable queue (SQS, Celery, BullMQ, a database-backed job table) over an in-process thread — a thread dies with the process, and the delivery is already acknowledged, so the data is simply gone. Raise this when the user is writing production code.

Test locally against the Xweather Postman collection, which ships sample payloads for the data sets; no subscription needed to exercise the handler.

Securing the endpoint

Layer these — no single one is sufficient:

1. HTTPS only. Non-negotiable: it encrypts the payload and keeps the URL token off the wire.
2. A secret token in the URL path — https://your-server.com/webhooks/xweather/a3f8c2d1e5b7. This is obscurity, not authentication: it cuts random scanning and accidental discovery. Useful, but never the only control.
3. API key verification. Xweather includes a client-provided key on every request, as an X-Api-Key header (recommended) or an api_key query parameter. Compare it on every request and reject mismatches before parsing anything. Use a constant-time comparison if the language offers one.
4. Payload validation. Check Content-Type is application/json, that the body parses, and that the top-level structure matches the expected envelope for that data set. Allow unknown extra fields — Xweather may add fields and commits to never removing them, so a strict schema that rejects unrecognised keys will break on a future release. Validate permissively.

Rotating a URL or key is a support request needing at least two business days' notice to avoid dropped deliveries. Worth designing for: have the receiver accept both the old and new key during a rotation window rather than cutting over atomically.

Registering

Xweather configures the subscription. The user supplies:

• The full HTTPS URL of each receiver. Use a fully qualified domain name, not a raw IP — DNS-based endpoints survive infrastructure changes.
• The data set(s) to subscribe to.
• The coverage area — a bounding box or polygon. Keep it a simple rectangle or low-vertex polygon; complex geometry causes performance problems.
• Per-environment URLs and keys. Up to three environments (dev / staging / production) are supported without discussion; more needs a support conversation.
• Format: JSON or GeoJSON. GeoJSON is the natural choice for polygon data sets (hail threats, alerts, fire perimeters) and for anything heading to a map.

The registration form Xweather expects looks like this:

Generate different secrets per environment — a staging key that also unlocks production defeats the purpose. When helping fill this in, produce the structure and let the user paste in their own secrets rather than inventing key values for them.

Xweather sends a test payload before enabling the full data set, so the first thing to watch for after registration is that single delivery landing and being acknowledged.

Debugging

Because the payload matches the API response, a fast way to know what to expect is to query the equivalent Weather API endpoint once via the weather-api skill and inspect the response shape.

Common patterns

• Severe weather alerting — subscribe to Alerts, Hail Threats, or Lightning Threats; on delivery, test the threat polygon against your asset/customer locations and notify whoever falls inside.
• Real-time lightning tracking — subscribe to Lightning or Lightning Analytics; feed strikes into a map layer or analytics pipeline. Note the Weather API charges ×10 for lightning; push avoids the repeated polling cost entirely.
• Observation ingestion — subscribe to Observations with a bounding box and upsert by station id to keep a local mirror current.
• Storm cell monitoring — subscribe to Storm Cells for position, movement vector, intensity, and hail probability; drive dispatch alerts or worksite closures.
• Fire weather operations — combine Fires (perimeters) with Alerts (red flag warnings) to automate escalation.
• Flood and river operations — subscribe to Rivers, compare stage readings against each gauge's flood stage, trigger downstream workflows.

Attribution is required

Xweather requires attribution wherever its data or imagery is displayed. This applies to all products — Weather API, Raster Maps, and MapsGL alike. Build it into anything you produce, and say so when handing over code or URLs that will end up in front of users.

The minimum is a link to https://www.xweather.com/ reading "Powered by Vaisala Xweather":

<a href="https://www.xweather.com/" target="_blank" title="Powered by Vaisala Xweather">Powered by Vaisala Xweather</a>

The logo may be substituted for the "Xweather" text. Light and dark variants exist in SVG and PNG:

<a href="https://www.xweather.com/" target="_blank" title="Powered by Vaisala Xweather">
  <img src="https://www.xweather.com/assets/logos/vaisala-xweather-logo-dark.svg" alt="Vaisala Xweather" height="40" />
</a>

Swap -dark for -light over a dark background, or .svg for .png. Using the logo brings rules: keep it unmodified, leave at least a 10px buffer of space around it, and only adjust lightness or opacity in greyscale. Don't rotate it, don't recolour it (monotone black or white excepted), and don't use the symbol without the Xweather name.

Full guide: https://www.xweather.com/docs/weather-api/resources/attribution

Related

The weather-api skill covers the pull equivalent and is the reference for payload field names — every webhook data set mirrors an endpoint documented there. Its access-cost.md explains the polling cost that webhooks are often adopted to eliminate.