When creating an integration you must specify a webhook url. The webhook url is used for notifying you once some asynchronous task, like a library track analysis, has finished or failed. Your webhook address must be facing the public internet.
Your webhook handler must return the status code
200, otherwise, the call will be treated as unsuccessful (and retried at a later point in time).
Furthermore, there should be no redirects happening (
30X status codes). All requests to your webhook will be aborted if the duration exceeds three seconds.
Delay the heavy lifting
We recommend not doing any heavy and time intensive tasks inside your webhook handler in order to not exceed the maximum invocation limit of three seconds. A better approach would be to delay the tasks until after the webhook response was sent, e.g. by writing the webhook payload to a worker queue, which is processed independently.
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.
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 that the request sent to your webhook originates from Cyanite.ai.
Cyanite.ai will send a
POST method HTTP request with
Content-Type: application/json to your specified webhook url.
Example implementation of verifying the request signature in Node.js.
New Webhook Format
When enqueuing a library track with the
Mutation.libraryTrackEnqueue fields on our API will automatically result in the new Webhook V2 payload.
Any usage of
Mutation.inDepthAnalysisEnqueueAnalysis should be migrated and the webhook should be
adjusted to accept the new webhook payload.
All library tracks that are enqueued using the
Mutation.libraryTrackEnqueue fields will result in the Webhook version 2 payload.
resource property indicates the resource that is affected. Currently, in the example payload above that is the
LibraryTrack with the ID
event property describes the status change of one of our four analysis types.
type property of the event can either be
InDepthAnalysis. The naming is consistent with the corresponding GraphQL object/union type.
status property can be either
The analysis result/error can then be fetched via the Cyanite.ai GraphQL API.