Send WeatherX alerts to your own server

You give us an address on your own server; we send one signed message to it every time something happens at your place. Most of this page is for whoever writes that server. Everything on it is what we already send — there is nothing to negotiate.

Is this the one you want?

Only if somebody on your side writes code. Every other destination we offer — email, Slack, Discord, Telegram, an alert on your screen — is one press and needs nobody technical. Start at all connect guides if that is what you are after.

This one is worth the work when the alert has to reach a program rather than a person: to open a barrier, hold a crane, page whoever is on duty, or write a row in your own records. Instead of the sentence a person reads, your server gets the numbers behind it — how far away the storm is, which way it is coming from, how far ahead the forecast was.

To set it up you need two things from your side: an address on a server of yours that is reachable from the internet over https, and somebody to write what happens when a message arrives. A place can carry this and an ordinary destination at the same time, so the crew still gets a message they can read.

If that is what you want, hand the rest of this page to whoever will build it. Nothing below needs you.

How to stop everything, without asking anybody

Your WeatherX email carries a Stop link at the bottom. Open it, and press the button on the page it shows. It stops every alert for that place and turns off every destination on it, at any hour. It needs no key and no reply.

Write to support@weatherx.earth, and ask us to take one destination off and leave the rest running.

Everything here needs your API key

Send it as an X-API-Key header. It is the key from your welcome message, and it never travels in a connect link — the two are separate on purpose.

Send yourself a real alert, now

You do not have to wait for weather. One call sends a real alert through the real senders:

POST /portal/sites/<place id>/test
X-API-Key: wx_live_…

It arrives as light rain half an hour away, and it says on its face that it is a test — in the first line of the message — so nobody can mistake it for weather. One a minute, twenty a day.

Take one destination off, and leave the rest

The Stop link above turns off everything at once. This takes off one and leaves the place watched. Ask for the list, then delete the one you mean:

GET /portal/sites/<place id>/channels
DELETE /portal/channels/<id>
X-API-Key: wx_live_…

Everything else on that place carries on receiving.

Add your endpoint

There is no approval screen and no connect link for this one. You register the address:

POST /portal/sites/<place id>/channels/webhook
X-API-Key: wx_live_…
Content-Type: application/json

{"url": "https://alerts.example.com/weatherx"}

The answer carries the signing secret once. It is never readable again, so store it as you would any other credential. The address must be https on port 443, must resolve to a public host, and must not redirect: we check it again at the moment of every send, not only when you register it.

What we send

One POST, content-type: application/json, one message per event per place. The body:

{
  "id": "evt_01K3XQ0R7YB2N4V8HJ5TZCDEFG",
  "type": "started",
  "event": "lightning",
  "decision": "STOP",
  "site": {
    "name": "Acme depot",
    "lat": 48.14,
    "lon": 11.58
  },
  "intensity": {
    "category": "high",
    "value": 3.0,
    "unit": "tier"
  },
  "eta": "2026-08-24T14:30:00Z",
  "eta_in_minutes": 18,
  "lead_minutes": 20,
  "distance_km": 12,
  "from_direction": "SW",
  "observed": true,
  "reissued": false,
  "cycle": "20260824_1410",
  "region": "europe",
  "sent_at": "2026-08-24T14:12:03Z",
  "observed_at": "2026-08-24T14:10:00Z"
}

Two more fields, on a clear message only

When the weather has passed, the same shape carries two fields the others do not:

{
  "id": "evt_01K3XQ0R7YB2N4V8HJ5TZCDEFG",
  "type": "ended",
  "decision": "LIGHTNING_CLEARED",
  "intensity": {
    "category": "peak",
    "value": 0.0,
    "unit": "tier"
  },
  "clear_since": "2026-08-24T15:00:00Z",
  "other_warnings": [
    "rain"
  ]
}

How it is signed

We follow the Standard Webhooks scheme, so a library you already have may verify it for you. Three headers travel with every message:

The signing secret is yours alone. You get it once, when the destination is made; if you lose it, write to support@weatherx.earth and we issue a new one. It begins with whsec_, and the part after that prefix is base64 — decode it to bytes before you use it as the HMAC key.

How to check it

import base64, hashlib, hmac

def is_ours(secret, headers, raw_body):
    """raw_body is the exact text we POSTed, not a re-dumped dict."""
    msg_id = headers["webhook-id"]
    stamp  = headers["webhook-timestamp"]

    # Refuse anything old: it is a replay, not an alert.
    import time
    if abs(time.time() - int(stamp)) > 300:
        return False

    key = base64.b64decode(secret.split("_", 1)[1])
    signed = f"{msg_id}.{stamp}.{raw_body}".encode()
    digest = hmac.new(key, signed, hashlib.sha256).digest()
    mine = "v1," + base64.b64encode(digest).decode()

    # Constant time, and accept any one of the space-separated
    # signatures the scheme allows.
    return any(hmac.compare_digest(mine, one)
               for one in headers["webhook-signature"].split(" "))

What your endpoint must do

1. Answer 2xx within five seconds. We wait five seconds. Anything else — a slow answer, a 4xx, a 5xx — counts as a failed delivery.

2. Accept the same message twice. We wait at least sixty seconds and try again after a failure. Use webhook-id to recognise the repeat.

3. Do not expect a late message. We stop trying after ten minutes and drop it. A weather warning that arrives after the weather is worse than none.

4. Do the work after you answer. Take the message, answer 200, then act on it. Work done inside the five seconds is work we are waiting for.

Rules for the address you give us

• It must be https and reachable from the public internet.
• It must be the final address. We do not follow redirects: a 307 answer is a failed delivery, not a new destination.
• Addresses that resolve to a private, loopback or link-local network are refused, at the moment of every send and not only when the destination is made.
• The path may carry your own token if you want a second gate. It never appears in our logs.

What arrives, and when

We look at your place every ten minutes. You get one message when weather is coming or has started, and one when it has passed. A quiet week is a quiet channel — nothing arrives to say that nothing is happening.

The first line is the decision: STOP means it is at the place now or within twenty minutes, PREPARE means it is coming, ALL CLEAR means it has passed.

The picture above is the same event as it reaches a person on Slack or in an inbox. Your endpoint gets the fields, not the sentences, and nothing is added to the payload: no stop line, no footer, nothing but the JSON above.

How to stop it

Refusing our POST does not stop it — we keep trying the next event, and the one after. Use the DELETE call above to take this endpoint off, or the Stop link to end every alert for the place at once.