Webhooks - Overview
How webhooks work
Webhooks use standard HTTP or HTTPS to communicate. The Xweather webhooks system sends a POST request to your server containing an update for the data set you requested. Data is sent in the same response format as it is returned by the Xweather API. This greatly simplifies adoption and transition from a poll-based architecture to a push-based architecture.
Your server should quickly return a response indicating that you received the data — typically a 201 or 202 status code — and then further process the data as you see fit. If your server takes too long to respond or returns an error status, the webhooks system may retry the delivery.
Request format
Each webhook delivery is an HTTP POST request sent to your registered endpoint.
Headers
| Header | Value | Description |
|---|---|---|
Content-Type | application/json | Indicates the format of the request body |
x-api-key | <client-generated-api-key> | Shared secret used to authenticate the webhooks source |
The x-api-key header contains an api key generated by the client to verify the delivery originated from Xweather. If you prefer, this key can also be a query parameter appended to your webhook URL instead of a header.
Body
The request body matches the standard Xweather API response format — either JSON or GeoJSON, depending on the format you prefer. Because the payload mirrors the Xweather API response structure, existing code that already parses API responses can be reused with minimal changes.
Responding to deliveries
Your endpoint must respond with an HTTP 2xx status code to confirm receipt. The response body is ignored. After acknowledging receipt, perform any long-running processing asynchronously (e.g., enqueue the payload to a background job) so you do not risk a timeout on the webhook delivery connection.
Retries
If your endpoint does not return a 2xx status, or if the connection times out, the webhooks system will retry delivery based on your configuration, typically no more than two to three times. If all retries fail, the delivery will be marked as failed and no further attempts will be made until the next update for that data set is available.
Multiple environments
You may register multiple URLs with the webhooks service to support separate development, staging, and production environments. If you need more than three environments, please contact Xweather Support to discuss your use case.