> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tariffs.nlead.ch/llms.txt
> Use this file to discover all available pages before exploring further.

# Tariff-change webhooks

> A signed POST when an operator's published tariffs change, instead of polling.

Operators publish new tariffs once a year and correct them at any time. Rather
than re-reading every operator to find out, subscribe: the service sends a
signed `POST` to your address when an operator's tariffs change.

Subscriptions need an [API key](https://docs.tariffs.nlead.ch/keys.md).

## Subscribing

```bash theme={null}
curl -X POST "$TARIFF_API/api/v1/webhooks" \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"url": "https://hooks.example.ch/tariffs",
       "vse_numbers": ["10063012345", "11008012345"]}'
```

Leave out `vse_numbers` to hear about every operator. The answer carries the
**secret** that signs your deliveries. It is shown this once; keep it.

```json theme={null}
{
  "id": 17,
  "url": "https://hooks.example.ch/tariffs",
  "vse_numbers": ["10063012345", "11008012345"],
  "secret": "q3Vx…",
  "signature": "X-Tariff-Signature: sha256=HMAC-SHA256(secret, body)"
}
```

| | |
| - | - |
| `GET /api/v1/webhooks` | Your subscriptions, each with its five latest deliveries. |
| `DELETE /api/v1/webhooks/{id}` | Stop one. |

At most ten subscriptions per key. Only public `https://` addresses are
accepted; a name that resolves to a private or loopback address is refused,
and checked again at every delivery.

## What arrives

Changes are detected once a night, after the collection run. Each changed
operator and tariff year is one delivery:

```http theme={null}
POST /tariffs HTTP/1.1
Content-Type: application/json
X-Tariff-Event: tariffs.changed
X-Tariff-Signature: sha256=5d1f…

{"event": "tariffs.changed", "vse_number": "10063012345", "period": 2027,
 "name": "Groupe E SA", "stage": "pipeline", "changed_at": "2026-11-02T03:41:07+00:00",
 "previous": "9c2e…", "fingerprint": "41ab…",
 "url": "https://ch-el-tarif-db.azurewebsites.net/api/v1/dsos/10063012345/tariffs?period=2027"}
```

The delivery says *that* something changed, not what: fetch `url` for the
tariffs as they are now. `previous` is `null` the first time an operator
publishes a year.

## Verifying the signature

Compute HMAC-SHA256 of the raw body with your secret and compare in constant
time.

```python Python theme={null}
import hashlib, hmac

def verified(body: bytes, header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header)
```

```js Node theme={null}
import crypto from "node:crypto";

function verified(body, header, secret) {
  const expected = "sha256=" +
    crypto.createHmac("sha256", secret).update(body).digest("hex");
  return header.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}
```

## Answering

Answer with any `2xx` within ten seconds. Anything else, a timeout, or a
redirect (redirects are not followed) counts as failed; the delivery is tried
again on the next nightly run, up to five times in all.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.