API reference
Webhooks Coming soon
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.
| Field | What it is |
|---|---|
type | animal.off_normal, later animal.back_to_normal. |
data.identity_id | The animal's name in your gallery, when identity is live; otherwise null and only track_id is set. |
data.p, validated | The state's probability, and always true: unvalidated states never send events. |
data.baseline | What "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
- Answer with any 2xx within 10 seconds. Anything else is retried with backoff for up to 3 days.
- Events can arrive more than once or out of order. Use
idto drop duplicates.