API keys and webhooks

The Ochy developer portal is the self-service interface for your API account. Sign in with your self-serve developer account or, for organizations, with an organization admin account (see get API access). The portal has the following tabs:

Tab	What it contains
Integration	Your API key and webhook configuration.
Usage & Credits	Credit balance, credit purchase (self-serve accounts), and usage over time.
Latest analyses	Analyses started with your API key, with an interactive results viewer.
Shoe recommendations	Shoe recommendations created with your API key, with their analyses and ranked matches.
Shoes	Shoe catalog for shoe recommendation. Organization admins manage the organization’s catalog; self-serve accounts manage their own.
Settings	Data retention and low-credit alerts.

The API section of the Ochy web app (Channels > API) has moved to the developer portal. For organization scopes, only organization admins can generate, rotate, or revoke API keys and change webhooks and settings.

API key management

Your API key authenticates every request to the Partner API. See authentication for how to pass it in your requests.

Generate a key

If you do not have an active key yet:

Open the Integration tab

Click Generate API Key

The portal creates a new key and displays it once. Self-serve developer accounts must verify their email address before they can generate a key.

Copy and store your key

Click the copy icon to save the key to your clipboard. Store it in a secure location such as an environment variable or a secrets manager.

The full key is shown only once, immediately after generation. If you navigate away without copying it, you will need to rotate the key to get a new one.

Rotate a key

Rotation revokes the current key and generates a replacement in a single step. Use this when you need a fresh key without downtime between revoke and generate.

Click Rotate Key

A confirmation dialog warns that existing integrations will stop working immediately.

Confirm the rotation

The old key is revoked and a new key appears in the banner. Copy it before leaving the page.

Update your integrations

Replace the old key in every service that calls the Ochy API.

Revoke a key

Revoking permanently deactivates the key. Any request using the revoked key will receive a 403 Invalid API Key error.

Click Revoke Key

A confirmation dialog explains that integrations using this key will stop working.

Confirm revocation

The key is deactivated. You can generate a new key at any time from the same tab.

Webhooks overview

Instead of calling GET /analysis/{analysis_id}/results repeatedly, you can ask Ochy to push status updates to an HTTPS endpoint you control. Your server receives JSON payloads as the analysis moves from queued to running, through progress milestones, to success or failure.

Webhooks are optional. Polling remains fully supported for debugging, gradual rollouts, or when delivery issues occur.

The integration flow:

Register a webhook URL once for your partner account — from the developer portal or with PUT /webhook. Use GET /webhook to read the current URL, enabled flag, signature status, and updated_at.
Opt in per analysis when you call POST /analysis/start with notify_via_webhook: true. If you omit it or set it to false, no webhook events are sent for that analysis.
Optionally enable HMAC signatures so your server can verify that events were sent by Ochy and that the request body was not modified.
Handle incoming POST requests on your URL. Each payload includes an event type, status, percentage, a monotonic sequence per analysis, and a timestamp.

Delivery is asynchronous: your endpoint should respond quickly (for example 2xx) and process the payload in the background if needed.

Each event is delivered at most once: Ochy makes a single attempt with a 10-second timeout and does not retry after a failure, timeout, or non-2xx response. Keep a slow fallback poll for analyses that have not reached a terminal event. See delivery guarantees.

Configure webhooks

You configure the webhook once per partner; you do not pass the URL on every POST /analysis/start.

From the developer portal

You need an active API key before you can configure a webhook.

Open the Integration tab

Enter your endpoint URL

Provide an HTTPS URL where Ochy will send POST requests. For example: https://your-app.com/webhooks/ochy.

Save the webhook

Click Save Webhook. The webhook is enabled automatically.

The URL must use HTTPS and its host must resolve to a public address. URLs that point to a private, loopback, or link-local address (for example 10.0.0.5, 127.0.0.1, or 169.254.169.254) are rejected with 400 and code invalid_webhook_url.

Once configured, use the toggle switch to enable or disable delivery without removing the URL. Click Edit URL to change the endpoint, then Update Webhook to save. Click Send Test Event to send a sample payload to your endpoint. The portal displays the HTTP status code and response latency so you can verify connectivity.

The test button is only available when the webhook is enabled. Toggle it on first if you need to test.

From the API

GET /webhook returns the stored url, enabled, and updated_at for your partner. If nothing has been saved yet, the response body is an empty JSON object ({}).

curl -s "https://partner-api.ochy-prod.com/webhook" \
  -H "Authorization: Bearer YOUR_API_KEY"

Use PUT /webhook with a JSON body:

{
  "url": "https://client.example.com/webhooks/ochy",
  "enabled": true,
  "signature": {
    "enabled": true
  }
}

Field	Type	Description
`url`	string	HTTPS URL that will receive `POST` requests from Ochy.
`enabled`	boolean	When `false`, no webhook traffic is sent until you enable it again.
`signature.enabled`	boolean	Optional. When `true`, Ochy signs webhook requests with HMAC-SHA256.

A successful PUT returns the same shape as GET: url, enabled, and updated_at. If you enable signatures for the first time, the response also includes a signature.secret. Copy and store it immediately; it is not returned by GET /webhook. Example response when a signing secret is generated:

{
  "url": "https://client.example.com/webhooks/ochy",
  "enabled": true,
  "updated_at": "2026-06-29T13:25:17Z",
  "signature": {
    "enabled": true,
    "algorithm": "HMAC-SHA256",
    "last4": "n6p8",
    "created_at": "2026-06-29T13:25:17Z",
    "updated_at": "2026-06-29T13:25:17Z",
    "secret": "YOUR_GENERATED_SIGNING_SECRET"
  }
}

Store signature.secret securely. Ochy only returns the full signing secret when it is generated or rotated.

When notify_via_webhook is true on start, the API checks that your partner webhook is valid and enabled. If it is not, the request is not rejected: the analysis starts with notifications disabled, and no events are sent for it. The decision to send webhooks for that analysis is fixed at start time and stored with the analysis.

Start an analysis with webhooks

Add an optional field to the same multipart request you already use for POST /analysis/start:

Field	Type	Default	Description
`notify_via_webhook`	boolean	`false`	If `true`, progress and completion events are delivered to your configured webhook URL for this analysis only.

Example (cURL):

curl -X POST "https://partner-api.ochy-prod.com/analysis/start" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "video=@runner_side.mp4" \
  -F "analysis_type=side_view" \
  -F "notify_via_webhook=true"

Events and payload format

For each analysis, events are emitted when:

processing starts (status moves to analyzing);
progress crosses each 10% boundary from 10% through 90% (if progress jumps, all crossed milestones are sent in order);
the analysis completes successfully (success, 100%);
the analysis fails (failed), at any progress value.

`event_type`	Typical `status`	Notes
`analysis.started`	`analyzing`	First processing signal for the run.
`analysis.progress`	`analyzing`	Progress milestones at 10%, 20%, … 90%.
`analysis.completed`	`success`	Final success; `percentage` is 100.
`analysis.failed`	`failed`	Terminal failure; `percentage` reflects last known progress.

Ochy sends POST requests to your webhook URL with a JSON body like:

{
  "analysis_id": "abc123",
  "event_type": "analysis.progress",
  "status": "analyzing",
  "percentage": 40,
  "sequence": 5,
  "timestamp": "2026-03-23T10:45:00Z"
}

Field	Description
`analysis_id`	Same identifier as `video_id` from the start endpoint.
`event_type`	One of `analysis.started`, `analysis.progress`, `analysis.completed`, `analysis.failed`.
`status`	Current analysis status (`analyzing`, `success`, or `failed`).
`percentage`	Progress from 0 to 100.
`sequence`	Per-analysis monotonic counter. Use it to order and deduplicate events.
`timestamp`	Time of the event in UTC (ISO 8601).

Completed:

{
  "analysis_id": "abc123",
  "event_type": "analysis.completed",
  "status": "success",
  "percentage": 100,
  "sequence": 11,
  "timestamp": "2026-03-23T10:46:30Z"
}

Failed:

{
  "analysis_id": "abc123",
  "event_type": "analysis.failed",
  "status": "failed",
  "percentage": 60,
  "sequence": 7,
  "timestamp": "2026-03-23T10:46:30Z"
}

Verify webhook signatures

Webhook signatures are optional but recommended for production integrations. Enable them from the developer portal or with signature.enabled: true in PUT /webhook. When signatures are enabled, Ochy adds two HTTP headers to every webhook request, including credits.low events:

Header	Description
`X-Ochy-Timestamp`	Unix timestamp in seconds, generated when the request is sent.
`X-Ochy-Signature`	Hex-encoded HMAC-SHA256 signature.

The signed value is:

<timestamp>.<raw request body>

To verify a webhook:

Read the raw request body bytes exactly as received.
Read X-Ochy-Timestamp and X-Ochy-Signature.
Reject old timestamps (for example, more than 5 minutes away from your server time).
Compute HMAC-SHA256 with your webhook signing secret over <timestamp>.<raw body>.
Compare the expected signature with X-Ochy-Signature using a constant-time comparison.

Do not parse and re-serialize the JSON before verifying the signature. JSON whitespace or key ordering changes will produce a different signature. Verify against the raw request body.

Python example

import hashlib
import hmac
import time


def verify_ochy_webhook(secret: str, timestamp: str, signature: str, raw_body: bytes) -> bool:
    # Reject replayed requests. Adjust the tolerance to your infrastructure.
    if abs(time.time() - int(timestamp)) > 300:
        return False

    signed_payload = timestamp.encode("utf-8") + b"." + raw_body
    expected = hmac.new(
        secret.encode("utf-8"),
        signed_payload,
        hashlib.sha256,
    ).hexdigest()

    return hmac.compare_digest(expected, signature)

Node.js example

import crypto from "crypto";

function verifyOchyWebhook(secret, timestamp, signature, rawBodyBuffer) {
  const ageSeconds = Math.abs(Date.now() / 1000 - Number(timestamp));
  if (ageSeconds > 300) {
    return false;
  }

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.`)
    .update(rawBodyBuffer)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(signature, "hex")
  );
}

Rotate the signing secret

Use POST /webhook/signature/rotate to generate a new signing secret:

curl -X POST "https://partner-api.ochy-prod.com/webhook/signature/rotate" \
  -H "Authorization: Bearer YOUR_API_KEY"

The response includes the new secret once:

{
  "enabled": true,
  "algorithm": "HMAC-SHA256",
  "last4": "7Tq2",
  "created_at": "2026-06-29T13:25:17Z",
  "updated_at": "2026-06-29T14:10:00Z",
  "secret": "YOUR_NEW_SIGNING_SECRET"
}

Update your webhook receiver to use the new secret.

Ordering and out-of-order delivery

Webhook delivery is asynchronous. In rare cases an older event might arrive after a newer one.

Each payload includes a sequence that increases for that analysis_id.
Process events in sequence order; if you receive a payload whose sequence is less than or equal to the last one you applied for that analysis, you can ignore it.

Ochy also uses internal ordering so that events for a given analysis are published in sequence; this reduces but does not eliminate the need for client-side ordering using sequence.

Delivery guarantees

Ochy sends each event once, with a 10-second timeout. If your endpoint is unreachable, slow, or answers with a non-2xx status, the event is dropped: there is no retry policy. This is intentional. Progress events are only useful when they arrive on time; an update delivered a few seconds late is already outdated. A retry policy would also mean repeatedly calling an endpoint that may be misconfigured (for example a wrong URL). To build a reliable integration:

Treat webhooks as a fast notification, not as a guaranteed log. Gaps in sequence are normal.
For every analysis without a terminal event (analysis.completed or analysis.failed), poll GET /analysis/{analysis_id}/results at a slow interval such as every 30 seconds, within your rate limit budget.
Events only carry analysis_id, which is the video_id returned by POST /analysis/start. They contain no client-side reference. If you never received the video_id, retry the start request with the same Idempotency-Key to get it back (see recovering a lost video_id).

Fallback: polling

You can always call:

GET /analysis/{analysis_id}/results

This endpoint continues to return the current status and percentage (and full results when status is success), whether or not webhooks are enabled. Use it for integration testing, manual checks, or when you need a single source of truth after delivery issues.

Usage and credits

The Usage & Credits tab of the developer portal shows:

Credits — your remaining analysis credits for the scope of your API key (personal or organization). Each analysis consumes one credit when started (see authentication).
Usage overview — for the selected period: accepted, successful, and failed analyses, analyses still processing, the success rate, and a chart of side view and back view analyses over time. Only analyses started through the Partner API are counted.

To add credits: self-serve developers buy them in the same tab (see get API access); organizations go through their Ochy contact. Analyses started with your API key are listed in the Latest analyses tab, where you can open each result in an interactive viewer. They do not appear in the Ochy mobile app or web app.

Low-credit alerts

Get warned before your balance runs out. Configure the alert in the portal Settings tab or with PUT /settings/low-credit-alerts:

Field	Description
`enabled`	Turns the alert on or off.
`threshold`	Number of credits, from 0 to 10000. The alert fires when an analysis brings the balance to or below the threshold. `0` never fires.
`webhookUrl`	Optional HTTP(S) URL that receives a `credits.low` event. It is separate from the analysis webhook URL and follows the same rules (public host only).

When the alert fires:

An email is sent to the person who last saved the alert settings.
If webhookUrl is set, Ochy sends a POST request with a credits.low event to it.

The alert fires once per crossing: it rearms when the balance rises above the threshold again (for example after buying credits), and it fires at most once per hour. Only credits consumed by analyses trigger it. Scopes with unlimited credits cannot configure alerts.

{
  "event_id": "8f14e45f-ceea-467a-9575-36a1a4d3b8c2",
  "event_type": "credits.low",
  "scope_type": "organization",
  "scope_id": "org_abc123",
  "threshold": 100,
  "balance_before": 101,
  "balance_after": 100,
  "trigger": "analysis_debit",
  "timestamp": "2026-10-05T10:45:00.000Z"
}

Field	Description
`event_id`	Unique identifier of the alert (UUID). Use it to deduplicate.
`event_type`	Always `credits.low`.
`scope_type`	`personal` or `organization`.
`scope_id`	Credit scope the alert belongs to.
`threshold`	Threshold configured when the alert fired.
`balance_before` / `balance_after`	Balance before and after the analysis that crossed the threshold.
`trigger`	What consumed the credit. Currently always `analysis_debit`.
`timestamp`	Time of delivery in UTC (ISO 8601).

When webhook signatures are enabled, credits.low requests carry the same X-Ochy-Timestamp and X-Ochy-Signature headers, signed with the same secret. Delivery is attempted once with a 10-second timeout and redirects are not followed, so respond with a 2xx quickly and keep an eye on your balance in the portal as a fallback.

Data retention

By default, Ochy keeps analysis videos and data indefinitely. In the portal Settings tab, you can set two independent retention periods:

Setting	What is deleted	Options
Video retention	Input video, analyzed video, and thumbnail.	Off (keep forever), 7, 30, 90, 180, or 365 days
Analysis data retention	The analysis itself and its result files.	Off (keep forever), 7, 30, 90, 180, or 365 days

Retention applies only to analyses started after you save the settings; the expiry date is fixed when the analysis starts. Expired content is deleted by a daily job. What changes in the API responses:

After the video retention period, GET /analysis/{analysis_id}/results still returns biomechanical_analysis, but thumbnail and output_video are omitted and video_expired is true.
After the analysis data retention period, the analysis is deleted and requests for it return 404.

Deletion is permanent. Copy any results you need to keep to your own storage before they expire.

Getting started

Guides

API key management

Generate a key

Rotate a key

Revoke a key

Webhooks overview

Configure webhooks

From the developer portal

From the API

Start an analysis with webhooks

Events and payload format

Verify webhook signatures

Python example

Node.js example

Rotate the signing secret

Ordering and out-of-order delivery

Delivery guarantees

Fallback: polling

Usage and credits

Low-credit alerts

Data retention

See also

​API key management

​Generate a key

​Rotate a key

​Revoke a key

​Webhooks overview

​Configure webhooks

​From the developer portal

​From the API

​Start an analysis with webhooks

​Events and payload format

​Verify webhook signatures

​Python example

​Node.js example

​Rotate the signing secret

​Ordering and out-of-order delivery

​Delivery guarantees

​Fallback: polling

​Usage and credits

​Low-credit alerts

​Data retention

​See also

API key management

Generate a key

Rotate a key

Revoke a key

Webhooks overview

Configure webhooks

From the developer portal

From the API

Start an analysis with webhooks

Events and payload format

Verify webhook signatures

Python example

Node.js example

Rotate the signing secret

Ordering and out-of-order delivery

Delivery guarantees

Fallback: polling

Usage and credits

Low-credit alerts

Data retention

See also