Skip to main content
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.

​
Overview

  1. Register a webhook URL once for your partner account with PUT /webhook. Use GET /webhook to read the current URL, enabled flag, and updated_at.
  2. Opt in per analysis when you call POST /analysis/start with notify_via_webhook: true. If you omit it or set it to false, behaviour is unchanged and no webhook events are sent for that analysis.
  3. 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.

​
Read the webhook configuration

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?apiKey=YOUR_API_KEY"

​
Configure the webhook

Use PUT /webhook with a JSON body: 
{
  "url": "https://client.example.com/webhooks/ochy",
  "enabled": true
}
FieldTypeDescription
urlstringHTTPS URL that will receive POST requests from Ochy.
enabledbooleanWhen false, no webhook traffic is sent until you enable it again.
A successful PUT returns the same shape as GET: url, enabled, and updated_at. This call creates your webhook configuration if none exists, or updates the URL and/or enabled flag. You configure the webhook once per partner; you do not pass the URL on every POST /analysis/start. When notify_via_webhook is true on start, the API checks that your partner webhook is valid and enabled. 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:
FieldTypeDefaultDescription
notify_via_webhookbooleanfalseIf 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?apiKey=YOUR_API_KEY" \
  -F "video=@runner_side.mp4" \
  -F "analysis_type=side_view" \
  -F "notify_via_webhook=true"

​
Events and frequency

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 types you may receive:
event_typeTypical statusNotes
analysis.startedanalyzingFirst processing signal for the run.
analysis.progressanalyzingProgress milestones at 10%, 20%, … 90%.
analysis.completedsuccessFinal success; percentage is 100.
analysis.failedfailedTerminal failure; percentage reflects last known progress.

​
Payload format

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"
}
FieldDescription
analysis_idSame identifier as video_id from the start endpoint.
event_typeOne of analysis.started, analysis.progress, analysis.completed, analysis.failed.
statusCurrent analysis status (analyzing, success, or failed).
percentageProgress from 0 to 100.
sequencePer-analysis monotonic counter. Use it to order and deduplicate events.
timestampTime 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"
}

​
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.

​
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.

​
See also