Webhooks

​

Configuration shape

{
  "url": "https://customer.example/webhooks/onvy",
  "events": ["users:created", "daily_records:updated", "ai_summaries:created"],
  "enabled": true,
  "hmac_secret": "replace-with-a-secret-of-at-least-16-characters"
}

• url must be HTTPS
• events must contain only supported event names
• enabled must be true to send deliveries
• hmac_secret must be at least 16 characters

​

Delivery payload

{
  "id": "wh_01J...",
  "created_at": "2026-03-05T18:10:27Z",
  "project_id": "proj_123",
  "org_id": "org_123",
  "api_version": 1,
  "events": [
    {
      "name": "daily_records:updated",
      "user_id": "user_123",
      "data": {
        "id": "score_123"
      }
    }
  ]
}

​

Headers

• X-Webhook-Signature
• X-Webhook-Timestamp
• X-Webhook-ID

​

Verify signatures

import hashlib
import hmac


def verify_signature(raw_body: bytes, secret: str, header_value: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode("utf-8"),
        raw_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, header_value)

​

Delivery semantics

• Delivery is asynchronous and at-least-once: your endpoint must be idempotent.
• Failed deliveries are retried with exponential backoff. The HTTP dispatch path retries on 429, 500, 502, 503, and 504 with total=3 and backoff_factor=1. Internal EventBridge dispatch into the webhook path is also retry-based and protected by a DLQ.
• Action semantics are encoded in the event name (for example daily_records:created, daily_records:updated, daily_records:deleted).

​

Idempotency

• The envelope id, also delivered as the X-Webhook-ID header, is unique per delivery.
• Per-event payloads carry stable resource IDs (for example a daily_records event’s data.id matches the resource ID returned by the API).

​

Large payloads

​

Event families

• users:*
• users.data_syncs:updated for provider sync state changes (for example deep-history loads)
• facts:*
• daily_records:*
• ai_summaries:* for meal, sleep, workout, daily, weekly, nutrition, trend, and impact summaries
• meals:*, including meals:updated when async nutrition analysis completes and a summary_id becomes available
• custom_records:*
• workouts:*
• lab_tests:*
• Batch lifecycle events such as batch.succeeded