Webhooks - Getting Started

Build your receiver endpoint

Create a web service that accepts POST requests at a chosen URL path. The endpoint must:

1. Parse the incoming JSON body.
2. Return a 202 HTTP status code immediately to acknowledge receipt.
3. Process or forward the data asynchronously after acknowledging.
4. Test your service locally or one of your public environments with the Xweather Postman collection  containing several sample payloads.

Example (Node.js / Express)

import express from 'express';
const app = express();
app.use(express.json());
 
app.post('/webhooks/xweather', (req, res) => {
  res.status(202).end(); // acknowledge immediately
  processPayload(req.body); // handle async
});
 
function processPayload(data) {
  console.log('Received webhook:', JSON.stringify(data));
}
 
app.listen(3000);

Example (Python / Flask)

from flask import Flask, request
import threading
 
app = Flask(__name__)
 
@app.route('/webhooks/xweather', methods=['POST'])
def receive_webhook():
    data = request.get_json()
    thread = threading.Thread(target=process_payload, args=(data,))
    thread.start()
    return '', 202
 
def process_payload(data):
    print('Received webhook:', data)

Secure your endpoint

Add a shared secret key to your endpoint URL path or use a custom header so that only Xweather can trigger your endpoint. See the Security guide for details.

Register your URL

Before registering, we strongly recommend your endpoint is reachable via a fully qualified domain name (FQDN) rather than a raw IP address. DNS-based endpoints are more resilient to infrastructure changes and easier to manage across environments.

Contact Xweather  or your account executive with:

• The full HTTPS URL of your receiver endpoint.
• The data set(s) you want to subscribe to (see Available Data).
• The bounding box or coverage area for your data set. It it recommended to keep these coverage areas as simple simple polygons or rectangles to avoid performance issues.
• List of your environment requirements (e.g. staging vs production) and relevant details such as URL and environment specific keys.

Xweather will configure the subscription and confirm when deliveries will begin. Please review the sample webhooks form below.

Verify deliveries

Once configured, Xweather will begin sending POST requests to your endpoint. Review your server logs to confirm payloads are arriving and your 202 responses are being sent correctly. Xweather will send a test payload prior to enabling the full data set.