Listening to webhook events

When creating an integration you have specified a webhook url. The webhook url is used for notifying you once some asynchronous task, like a file analysis, has been completed. Your webhook address must be public facing to the internet. Furthermore, there should be no redirects. All requests to your webhook will be aborted if it's duration exceeds three seconds.

You can find an example webhook integration here: Cyanite Integration Example on Github

Cyanite.ai will send a POST method request with Content-Type: application/json.

The request body always has the following structure:

{
"type": "EVENT_TYPE",
"data": {
"eventParameter1": "",
"eventParameter2": ""
}
}

Furthermore, the Signature header of the request includes a HMAC based on the Webhook secret set during the integration creation process. You should use this signature in order to verify the request body.

A webhook should return the status code 200, otherwise, the call will be treated as unsuccessful (and retried at a later point in time).

Furthermore, the webhook does (in contrast to the GraphQL API), for security reasons, only include the necessary data. In most cases, this means only the id of the processed entity.

Available Event Types

All requests will use the POST method and the Content-Type: application/json.

Event TypeExample Body
TEST{ "type": "TEST", "data": null }
IN_DEPTH_ANALYSIS_FAILED{ "type": "IN_DEPTH_ANALYSIS_FAILED", "data": {"inDepthAnalysisId": "86"} }
IN_DEPTH_ANALYSIS_FINISHED{ "type": "IN_DEPTH_ANALYSIS_FINISHED", "data": {"inDepthAnalysisId": "86"} }
SPOTIFY_TRACK_ANALYSIS_FAILED{ "type": "SPOTIFY_TRACK_ANALYSIS_FAILED", "data": {"spotifyTrackId": "4uLU6hMCjMI75M1A2tKUQC"} }
SPOTIFY_TRACK_ANALYSIS_FINISHED{ "type": "SPOTIFY_TRACK_ANALYSIS_FINISHED", "data": {"spotifyTrackId": "5n8Aro6j1bEGIy7Tpo7FV7"} }
IN_DEPTH_ANALYSIS{ "type": "IN_DEPTH_ANALYSIS", "id": 9999, "event": {"type": "FAST_MUSICAL_ANALYSIS", status: "FINISHED"}}

InDepthAnalysis and SpotifyTrackAnalysis

For a finished or failed analysis of a library or spotify track the Cyanite.ai API sends the IN_DEPTH_ANALYSIS_FAILED, IN_DEPTH_ANALYSIS_FINISHED, SPOTIFY_TRACK_ANALYSIS_FAILED and SPOTIFY_TRACK_ANALYSIS_FINISHED events.

FastMusicalAnalysis and FullScaleAnalysis

The FastMusicalAnalysis and FullScaleAnalysis use the new webhook event payload schema. Instead of using the event type as an identifier for the resource and the status it utilizes a more flexible nested structure that is more resource oriented.

Both the FastMusicalAnalysis and the FullScaleAnalysis are enqueued for spotify tracks and library tracks (InDepthAnalysis records). The status of those analyses is reported with a webhook containing the following payload:

{
"type": "IN_DEPTH_ANALYSIS", // resource type
"id": "9999", // id of the resource
"event": {
"type": "FULL_SCALE_MUSICAL_ANALYSIS", // analysis type
"status": "FINISHED" // status of the analysis "FINISHED" or "FAILED"
}
}

Verifying the Request Signature

Example implementation of verifying the request signature in Node.js.

"use strict";
const crypto = require("crypto");
const verifySignature = (secret, signature, body) => {
const hmac = crypto.createHmac("sha512", secret);
hmac.write(body);
hmac.end();
const compareSignature = hmac.read().toString("hex");
if (signature !== compareSignature) {
throw new TypeError("Invalid signature");
}
};