Understanding Webhooks
Analysis in Cyanite is asynchronous: you upload a track, and Cyanite notifies your webhook when its results are ready. This page explains what these notifications contain and how they're delivered, so you can build a handler that never loses one. To receive your first notification, follow the Quick Start.
Overview
Event types
Cyanite sends one of two events to your endpoint:
| Event type | Sent when |
|---|---|
analysisJob/finished | The analysis finished and the track's model outputs can be fetched. |
analysisJob/failed | The analysis failed. The notification doesn't include a failure reason. |
Payload
The request body is a JSON object with the following structure:
{
"type": "analysisJob/finished",
"timestamp": "2026-10-29T12:00:00.000Z",
"data": { "track": { "id": "libtr_01KFZQGZ6FJAK5C320" } }
}
| Field | Description |
|---|---|
type | The event type, analysisJob/finished or analysisJob/failed. |
timestamp | ISO 8601 time when the analysis finished or failed, not when it was sent. |
data.track.id | The ID of the Library Track that was analyzed. |
The notification identifies the track, not its results. Fetch the results with
GET /v1/library-tracks/{id}/models
after you receive analysisJob/finished.
Headers
Every request carries three headers:
| Header | Content |
|---|---|
webhook-id | The notification's unique ID. It stays the same across retries. |
webhook-timestamp | Unix timestamp (seconds) of this delivery attempt. It changes with every retry. |
webhook-signature | An HMAC-SHA256 signature of the request. Use it with your webhook secret to verify the notification. |
Cyanite configures your webhook URL and webhook secret for your account. To change the URL or rotate the secret, contact Cyanite.
Verifying signatures
Cyanite signs every notification according to the Standard Webhooks specification. Verifying the signature ensures that a request was sent by Cyanite and wasn't changed on the way. Standard Webhooks provides libraries for many languages, such as TypeScript, Python, PHP and Rust, that verify a request's body and headers for you.
A few things to keep in mind:
- Verify the raw body. The signature is computed over the request body as sent. Verify it before you parse the body: re-serialized JSON can differ in whitespace or key order, and the signature won't match.
- Keep your clock in sync. The libraries reject notifications whose
webhook-timestampis more than 5 minutes away from your server's time. This protects you against replayed requests. - Protect your secret. Your webhook secret is base64-encoded. Pass it to
the library with the
whsec_prefix, as shown in the Quick Start. Treat it like a password: keep it out of your source code and logs.
Respond with a 4xx status code, such as 400, when verification fails, and
don't process the request.
Delivery and retries
Cyanite sends each notification as an HTTP POST request to your webhook URL.
- Delivered: your endpoint responds with any
2xxstatus code. - Failed: your endpoint responds with any other status code, including a
3xxredirect, doesn't respond within 5 seconds, or can't be reached.
Redirects aren't followed. Configure the final URL of your endpoint as your
webhook URL, including the https:// scheme and the exact path, so that it
responds without redirecting.
A failed delivery is retried up to 4 times, so a notification is attempted at most 5 times in total. After that, Cyanite stops retrying this notification.
The timeout and the number of retries are the current defaults. They can change. Build your handler so that it responds quickly and handles repeated notifications, and don't rely on the exact retry schedule.
Because a 2xx response ends the delivery, respond only once you have
verified the notification and stored it, for example in a database or a
queue. If your endpoint responds first and then fails, Cyanite has no reason to
send the notification again, and it's lost. Process the stored notification
afterwards, outside of the request, so you stay well below the 5-second timeout.
Duplicates and ordering
Cyanite delivers every notification at least once. You can receive the same notification more than once, for example when your endpoint stored it but the response didn't reach Cyanite in time. There are two kinds of repeats:
- The same notification, delivered again. A retried notification keeps its
webhook-idheader. Store thewebhook-idwith a unique constraint and ignore notifications you've already stored. - A new notification for the same track. When Cyanite analyzes a track
again, you receive another
analysisJob/finishedfor the same track, with a newwebhook-id. Treat it as "the results of this track have changed" and fetch them again. Writing results as an upsert by track ID handles this case as well as a notification processed twice.
Notifications are not guaranteed to arrive in order. Use the body's timestamp
if you need to know which analysis happened last.
Failed analyses
An analysisJob/failed notification means Cyanite couldn't analyze the track.
It doesn't include the reason. A common cause is a corrupt file or a file that
doesn't meet the
upload requirements, an MP3
of at most 20 MB and 15 minutes.
Check the file, then delete the failed Library Track and upload the file again. Don't keep both, or you'll have duplicates in your Library. If the analysis of a valid file fails again, contact Cyanite with the Library Track ID.
When deliveries keep failing
If your endpoint is down for longer than Cyanite retries a notification, the notification is lost, and there's no API to list or redeliver past notifications. If deliveries keep failing, Cyanite can also pause notifications to your webhook. Contact Cyanite to resume them once your endpoint works again.
Reconcile from your side instead: remember the Library Track IDs you've uploaded,
and occasionally poll
GET /v1/library-tracks/{id}/models for
the tracks that still have no results after a grace period well above your usual
analysis time. While the analysis is running, the response has an empty items
list. Once every model output you need is in items, process the track as if
its notification had arrived. Poll only tracks that are still missing results,
and wait longer between polls of the same track: every poll counts towards your
limits.
If a track has no results after a day, or notifications keep failing although
your endpoint works, contact Cyanite with the
affected Library Track IDs or webhook-ids.
Production checklist
- The signature is verified on the raw body, and requests that fail
verification get a
4xxresponse. - Notifications are stored, with
webhook-idas a unique key, before the handler responds. - The handler responds within 5 seconds and doesn't call the Cyanite API while Cyanite waits for the response.
- A background worker processes stored notifications, retries failed API calls and writes results idempotently.
analysisJob/failedis handled.- A reconciliation job polls tracks that are missing results.
- The server clock is synchronized, for example with NTP.
Further reading
- Quick Start: receive your first notification.
- Understanding Limits: what polling costs.