Docs
Docs pages

API reference

Webhooks Coming soon

This is a spec, not a running feature. Nothing on this page is built yet: there is no endpoint to register a webhook and no events are sent. We publish it so you can plan, and we'll change it if partners need something different.

A webhook tells your server when something about an animal changes, so you don't have to poll. The first event planned is "off her normal": an animal whose behaviour has moved away from its own usual pattern.

When it will fire

Only for a state that has passed a locked test. Today none of calm, stressed, in pain, lame or likely unwell has, so even when webhooks ship, animal.off_normal will not fire until one does. See what is live. Preview / off

Payload

POST https://your-server.example/vitals-webhook
Content-Type: application/json
Vitals-Signature: t=1795219200,v1=5f2b6c...e81a

{
  "id": "evt_9mQ2kLw7sXa1",
  "type": "animal.off_normal",
  "created": 1795219200,
  "api_version": "v1",
  "data": {
    "camera_id": "cam_barn_2",
    "track_id": 12,
    "identity_id": "cow-0412",
    "species": "cattle",
    "state": "lame",
    "p": 0.81,
    "validated": true,
    "baseline": { "days": 14, "metric": "lying_hours_per_day", "usual": 11.6, "now": 7.9 },
    "window": { "from": "2026-12-03T00:00:00Z", "to": "2026-12-04T00:00:00Z" },
    "request_id": "req_Lr0d1sY2rE9q"
  }
}

The values above are made up to show the format.

FieldWhat it is
typeanimal.off_normal, later animal.back_to_normal.
data.identity_idThe animal's name in your gallery, when identity is live; otherwise null and only track_id is set.
data.p, validatedThe state's probability, and always true: unvalidated states never send events.
data.baselineWhat "normal" was for this animal and what it is now.

Signing

Each event will be signed with a secret you get when you register the endpoint. Vitals-Signature holds a Unix time t and v1, the hex HMAC-SHA256 of t + "." + raw body with your secret. Reject the event if the signature doesn't match or t is more than 5 minutes old.

import hmac, hashlib, time

def verify(raw_body: bytes, header: str, secret: str, tolerance_s: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t, sig = parts["t"], parts["v1"]
    want = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(want, sig) and abs(time.time() - int(t)) <= tolerance_s

Delivery