Skip to main content

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 typeSent when
analysisJob/finishedThe analysis finished and the track's model outputs can be fetched.
analysisJob/failedThe 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" } }
}
FieldDescription
typeThe event type, analysisJob/finished or analysisJob/failed.
timestampISO 8601 time when the analysis finished or failed, not when it was sent.
data.track.idThe 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:

HeaderContent
webhook-idThe notification's unique ID. It stays the same across retries.
webhook-timestampUnix timestamp (seconds) of this delivery attempt. It changes with every retry.
webhook-signatureAn 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-timestamp is 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 2xx status code.
  • Failed: your endpoint responds with any other status code, including a 3xx redirect, 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.

note

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-id header. Store the webhook-id with 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/finished for the same track, with a new webhook-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 4xx response.
  • Notifications are stored, with webhook-id as 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/failed is handled.
  • A reconciliation job polls tracks that are missing results.
  • The server clock is synchronized, for example with NTP.

Further reading​