Observations webhook

What it is for

A logger, a buoy gateway or a phone app that wants to push readings for a site sends them to POST /sites/{site_id}/observations. The readings land next to the site's other observations (source webhook, scale site) and are used by the signals and the assistant like any other site-scale observation. They are operator records: the agency tools never return them (REST API).

Authentication

Send the deployment's webhook key in the X-API-Key header. It is one machine credential set by the deployment's administrator (not an agency key, not issued through the access request form) and it is administrator-equivalent: give it only to systems you control. When no key is configured the endpoint is disabled and answers 503; a missing or wrong key is 401.

Request

A JSON array of 1 to 10,000 items, each shaped like a SOSA observation (observed property, simple result with unit, result time, sensor):

Observable properties

The property ids the webhook accepts, with the canonical unit each is stored in:

Units

Case and spaces are ignored; the QUDT name (for example DEG_C or unit:DEG_C) and the stored spelling are always accepted. Other spellings are converted to the canonical unit; the original value and unit are kept in the row's metadata.

Rules

• All or nothing. Any invalid item answers 422 and nothing is stored. detail is a list of {loc, msg, type} with loc = ["body", <item index>, <field>]. Two items with the same property, sensor, depth and time are refused too (422 on the later one).
• Idempotent. Re-sending an observation (same site, property, sensor, depth and time) updates its value in place; the response counts it under updated.
• Stored row. Variable = property, value and unit in the canonical unit, time in UTC, product webhook:<sensor_id> (or webhook without a sensor), metadata with the sensor, the time received and, when converted, the value and unit as sent.
• 404 for an unknown site; 409 for a site that has no operator account to own the records.
• Clock skew: a time more than 1 hour in the future is refused.

Example of the shape

Shape only: the values are placeholders, not readings.

curl -X POST https://coastal-intelligence.triskelionaisystems.com/api/sites/<site id>/observations \
  -H "X-API-Key: $WEBHOOK_API_KEY" -H "Content-Type: application/json" \
  -d '[{"property":"<property id>","value":"<number>","unit":"<unit>","time":"<YYYY-MM-DDThh:mm:ssZ>","depth_m":"<number, optional>","sensor_id":"<id, optional>"},{"property":"<property id>","value":"<number>","unit":"<unit>","time":"<YYYY-MM-DDThh:mm:ss+01:00>"}]'

201 Created with:

{
  "site_id": "<site id>",
  "received": "<number of items>",
  "observations": {
    "inserted": "<count>",
    "updated": "<count>"
  },
  "variables": [
    "<property id>",
    "<...>"
  ],
  "products": [
    "webhook",
    "webhook:<sensor_id>"
  ]
}