Webhooks

One webhook can be registered per Partner account. Clutch sends JSON POST requests with the registration token in X-Clutch-Webhook-Token.

GET /partner/webhook

Returns the current URL and updated_at, or data: null when no webhook is registered. The token cannot be read after registration.

PUT /partner/webhook

Registers or replaces the webhook. The URL must use HTTPS and a public hostname; IP addresses and internal hostnames are rejected.

Body:

{
  "url": "https://partner.example.com/clutch-webhook"
}

Sample response

{
  "data": {
    "url": "https://partner.example.com/clutch-webhook",
    "token": "<webhook-token>"
  }
}

The token is shown only in this response. Every PUT generates a new token and invalidates the previous one.

DELETE /partner/webhook

Removes the registration. deleted is false when no webhook was registered.

{
  "data": {
    "deleted": true
  }
}

Delivery

Clutch sends video.status_changed when a Partner-owned recording enters COMPLETED, COMPLETED_EMPTY_COURT, OK, OK_EMPTY_COURT, DELAYED_PROCESSING, CANCELLED, FAILED_DEVICE_OCCUPIED, or FAILED_DEVICE_OFFLINE. Standard recordings also emit UPLOADED and UPLOAD_FAILED.

{
  "event": "video.status_changed",
  "video_id": "B92BFC8A-2454-4632-9580-F96E99FB7C85",
  "status": "OK",
  "device_id": "4580f207-b672-4df0-83eb-110cc408466b",
  "start_time": "2026-08-01T17:02:00Z",
  "end_time": "2026-08-01T18:30:00Z",
  "title": "Example Court",
  "run_version": 1,
  "occurred_at": "2026-08-01T18:31:00Z"
}

run_version is the processing run that produced the current results. A reprocess sends the event again for the same video_id with a higher run_version and renumbers every player-N ID, with no mapping from the old IDs. When the value goes up for a recording you already have, fetch GET /video/{video_id}/results again and rebuild anything stored against the old IDs.

Clutch sends player.identification_changed when a linked Partner player gains, changes, or loses their player slot in a Partner-owned recording, once per Partner player ID.

{
  "event": "player.identification_changed",
  "event_id": "5f0e6c2a-8f0b-4d2a-9c31-3e0b9f7c1a44",
  "video_id": "B92BFC8A-2454-4632-9580-F96E99FB7C85",
  "partner_player_id": "partner_player_813742",
  "ai_player_id": "player-14",
  "previous_ai_player_id": null,
  "pair": "pair-1",
  "occurred_at": "2026-08-01T19:40:00Z"
}

ai_player_id and pair are null when the player left their slot, and previous_ai_player_id is the slot they held before. Deduplicate on event_id.

This webhook reports slot changes. It does not confirm account linking or report edits limited to grouping, skipped tracks or teams. Confirm linking with GET /partner/players/{partner_player_id}/link and saves with the PATCH response. Refetch GET /partner/recordings/{video_id}/annotations after a slot-change event or when reopening the editor.

Compare X-Clutch-Webhook-Token with the token returned by PUT and return a 2xx response within five seconds. Delivery is best effort and events may arrive out of order; reconcile missed events through the status, recording-list, players and annotations endpoints.