Webhooks - Security

Because your webhook endpoint is a publicly accessible URL, it is important to ensure that only Xweather can trigger it. The following practices are recommended.

Shared secret in the URL path

The simplest approach is to embed a secret token in the URL path that you register with Xweather:

https://your-server.com/webhooks/xweather/a3f8c2d1e5b7

This acts as a form of endpoint obscurity. It helps reduce random scanning, accidental discovery, and unwanted traffic. Only Xweather (and your team) will know this URL.

API key authentication

For additional security, you can provision an API key that Xweather will include with every webhook request. This allows your endpoint to verify that incoming requests originate from Xweather.

The API key can be passed in one of two ways:

Header (recommended)

X-Api-Key: <your-api-key>

Query parameter

https://your-server.com/webhooks/xweather?api_key=<your-api-key>

Provide your preferred method and key value when registering your endpoint with Xweather.

Rotating credentials

If your URL or API key is ever compromised, you can request an update at any time. Please provide at least two business days’ notice before the change takes effect to avoid any interruption in webhook deliveries.

HTTPS only

Always use HTTPS for your webhook endpoint. This encrypts the payload in transit and prevents eavesdroppers from intercepting your weather data or discovering the URL token.

Validate the payload

Even with a secret URL, you should validate that incoming requests look like legitimate Xweather payloads before processing them. Check that:

• The Content-Type header is application/json.
• The body can be parsed as valid JSON.
• The top-level fields match the expected Xweather API response structure for the data set you subscribed to. Please note, Xweather may add additional fields in the future, so allow for extra fields rather than requiring an exact match. Xweather will never remove fields.