Webhooks

Webhooks let Reprtoir notify your systems in real time when a long-running operation finishes, so you don't have to poll the API. Whenever a subscribed event occurs, Reprtoir sends an HTTP POST request to the URL you configured, with a JSON body describing what happened.

Configuring a webhook

Webhooks are managed in your Reprtoir account from Settings → Integrations → Webhooks.

Field	Description
Name	A label to help you identify the webhook.
API Key	The API key the webhook is bound to (see Scoping below).
Event Types	One or more events this endpoint should receive.
URL	The HTTPS endpoint Reprtoir will call.

Scoping

A webhook is bound to a single API key. It only receives events for operations that were initiated with that same API key. If you use several API keys, register one webhook per key (or per key/event combination).

Delivery & retries

Requests are sent as POST with the header Content-Type: application/json.
The body is the raw JSON payload (documented per event below).
Your endpoint must answer with a 2xx status code. Any other response (or a timeout) is treated as a failure and the delivery is retried automatically with an exponential back-off.
Deliveries are asynchronous: expect the call a short time after the triggering operation completes, and do not assume ordering between two events.

Payload shape

Every payload is a flat JSON object. The first key is always event_type, followed by the event-specific fields:

{
  "event_type": "<the event type>",
  "...": "event-specific fields"
}

`api_upload_success`

Sent when an asset uploaded through the Uploads API has been successfully imported and attached to its resource (album artwork, track audio, or album attachment).

Payload fields

Field	Type	Description
`event_type`	string	Always `api_upload_success`.
`uuid`	string	UUID of the upload. Matches the `uuid` returned when the upload was created.
`type`	string	The asset type: `album_artwork`, `track_audio`, or `album_attachment`.
`status`	string	Always `success` for this event.
`reference`	string \| null	The `reference` you passed when creating the upload, echoed back for correlation.
`error_message`	null	Always `null` for this event.

Example payload

{
  "event_type": "api_upload_success",
  "uuid": "19f71e2e-81ca-4cbb-a239-897ef011e912",
  "type": "track_audio",
  "status": "success",
  "reference": "ext-track-4218",
  "error_message": null
}

`api_upload_error`

Sent when an asset uploaded through the Uploads API could not be imported (corrupted file, unsupported format, failed validation, …). The uploaded resource is left untouched.

Payload fields

Field	Type	Description
`event_type`	string	Always `api_upload_error`.
`uuid`	string	UUID of the upload. Matches the `uuid` returned when the upload was created.
`type`	string	The asset type: `album_artwork`, `track_audio`, or `album_attachment`.
`status`	string	Always `error` for this event.
`reference`	string \| null	The `reference` you passed when creating the upload, echoed back for correlation.
`error_message`	string \| null	A human-readable description of the failure. Multiple errors are joined with `;`.

Example payload

{
  "event_type": "api_upload_error",
  "uuid": "7c1d4b90-3f2e-4a6b-9c15-8b0e2a4d7f33",
  "type": "album_artwork",
  "status": "error",
  "reference": "ext-cover-991",
  "error_message": "Image is too small (min. 1500x1400)"
}

`api_audio_similarity_ready`

Sent when a reference audio uploaded through the Reference Audios API has finished processing and is ready to be used as a query for audio-similarity search — or when that processing failed.

This event covers both outcomes; inspect the status field to tell them apart.

Payload fields

Field	Type	Description
`event_type`	string	Always `api_audio_similarity_ready`.
`uuid`	string	UUID of the reference audio. Matches the `uuid` returned when the upload URL was created.
`status`	string	`success` when the audio is ready, `failed` when processing could not complete.
`ref`	string \| null	The `ref` you passed when requesting the upload URL, echoed back for correlation.
`errors`	array of strings	Empty on success. On failure, one or more human-readable error messages.

Example payload — success

{
  "event_type": "api_audio_similarity_ready",
  "uuid": "fa529f6d-2118-4d71-bd51-91d35de8aeb8",
  "status": "success",
  "ref": "catalog-import-42",
  "errors": []
}

Example payload — failure

{
  "event_type": "api_audio_similarity_ready",
  "uuid": "b83e0c27-9a41-4d8f-badc-1f6e5a90c4e2",
  "status": "failed",
  "ref": "catalog-import-42",
  "errors": [
    "Audio analysis failed."
  ]
}

Event reference

Event type	Triggered when	`status` values
`api_upload_success`	An API upload was imported successfully	`success`
`api_upload_error`	An API upload failed to import	`error`
`api_audio_similarity_ready`	A reference audio finished processing (or failed)	`success`, `failed`