🎵 Webhook Integration Guide

This document explains how to use the webhook_url and webhook_secret parameters when creating music generation tasks, and provides complete webhook payload examples for the three supported platforms: Suno, Nuro, and Producer.

1) Parameters

`webhook_url`

Type: string
Optional

Callback URL. When a task reaches a final state (succeeded,streaming or failed), the system sends an HTTP POST request with an application/json body to this URL.

Supported platforms: suno, nuro, producer

Use HTTPS whenever possible

Your endpoint should return a 2xx status to acknowledge receipt

Example:

{
  "webhook_url": "https://yourdomain.com/api/music-callback"
}

`webhook_secret`

Type: string
Optional

Secret used to sign the webhook payload so your server can verify authenticity.

If a task provides webhook_secret during creation, the delivery service signs with that value; otherwise it falls back to a default secret managed by us.

Every delivery includes the following signature headers:

X-Webhook-Timestamp: <unix_seconds>
X-Webhook-Signature: sha256=<hex>

When verifying, build the string ${timestamp}.${rawBody} using the exact raw body bytes captured before parsing.

message = `${timestamp}.${rawBody}`
signature = HMAC_SHA256(webhook_secret, message)

Reject requests whose timestamp is outside a 3–5 minute window to reduce replay risk.

Example:

{
  "webhook_secret": "your-secret-key"
}

2) Delivery Semantics

HTTP Method: POST

Content-Type: application/json

Trigger: Sent once a task transitions to a terminal state (typically succeeded; on errors you may receive failed).

Retries: If your server returns a non-2xx status code or times out, the webhook may be retried. Implement idempotency using task_id.

Idempotency hint: Deduplicate using (task_id, platform) and the provided headers.

Request headers:

X-Webhook-Id – unique event identifier, duplicated in Idempotency-Key.

X-Webhook-Event – event type such as song.completed or song.failed.

X-Webhook-Timestamp – Unix timestamp (seconds) when the payload was signed.

X-Webhook-Signature – sha256=<hex> signature computed with the secret.

Idempotency-Key – mirrors X-Webhook-Id for frameworks that expect it.

3) Security & Verification

Below is a minimal Node.js example that verifies the signature:

Python (FastAPI) example:

4) Local Testing Utilities

During local development expose your local port with a tunnelling service (such as ngrok or Cloudflare Tunnel), then point webhook_url to the public HTTPS address.

Configure the tunnelled endpoint with the same secret you used when creating the task so the HMACs match.

The response includes the parsed payload, raw body, and verification.expected/verification.provided fields to help troubleshoot mismatches.

The endpoint responds with 200 on success and 400 when headers or signatures are invalid, mirroring production behaviour.

5) Webhook Payload Examples (Success)

5.1 Suno — `event: "song.completed"`

{
  "code": 200,
  "data": [
    {
      "clip_id": "30264033-2b01-43a7-8779-2a834b067486",
      "state": "succeeded",
      "title": "Sunshine in My Pocket",
      "tags": "electric with claps and synths, happy, pop",
      "lyrics": "[Verse]\nWoke up today the sky was gold\nA story untold\nA treasure to hold\nMy feet on fire the ground feels light\nDancing shadows chase the night\n\n[Chorus]\nI got sunshine in my pocket\nA melody that won't stop it\nEvery step feels like a spark\nLighting up the world from dark\n\n[Verse 2]\nThe trees are swaying to my beat\nThe pavement hums beneath my feet\nWhistling wind it sings along\nLife's a stage and I'm the song\n\n[Prechorus]\nNo time for sorrow no time for gray\nWe’re painting colors all the way\n\n[Chorus]\nI got sunshine in my pocket\nA melody that won't stop it\nEvery step feels like a spark\nLighting up the world from dark\n\n[Bridge]\nTurn it up turn it loud\nLet it echo through the crowd\nEvery heart every soul\nTogether now we’re whole",
      "image_url": "https://cdn2.suno.ai/image_30264033-2b01-43a7-8779-2a834b067486.jpeg",
      "audio_url": "https://cdn1.suno.ai/30264033-2b01-43a7-8779-2a834b067486.mp3",
      "video_url": null,
      "created_at": "2025-10-12T13:13:02.488Z",
      "gpt_description_prompt": null,
      "duration": "104.88",
      "negative_tags": null,
      "style_weight": null,
      "weirdness_constraint": null,
      "mv": "chirp-v5"
    },
    {
      "clip_id": "f5250a71-1c27-4cc9-a302-99f2d64a4790",
      "state": "succeeded",
      "title": "Sunshine in My Pocket",
      "tags": "electric with claps and synths, happy, pop",
      "lyrics": "[Verse]\nWoke up today the sky was gold\nA story untold\nA treasure to hold\nMy feet on fire the ground feels light\nDancing shadows chase the night\n\n[Chorus]\nI got sunshine in my pocket\nA melody that won't stop it\nEvery step feels like a spark\nLighting up the world from dark\n\n[Verse 2]\nThe trees are swaying to my beat\nThe pavement hums beneath my feet\nWhistling wind it sings along\nLife's a stage and I'm the song\n\n[Prechorus]\nNo time for sorrow no time for gray\nWe’re painting colors all the way\n\n[Chorus]\nI got sunshine in my pocket\nA melody that won't stop it\nEvery step feels like a spark\nLighting up the world from dark\n\n[Bridge]\nTurn it up turn it loud\nLet it echo through the crowd\nEvery heart every soul\nTogether now we’re whole",
      "image_url": "https://cdn2.suno.ai/image_f5250a71-1c27-4cc9-a302-99f2d64a4790.jpeg",
      "audio_url": "https://cdn1.suno.ai/f5250a71-1c27-4cc9-a302-99f2d64a4790.mp3",
      "video_url": null,
      "created_at": "2025-10-12T13:13:02.488Z",
      "gpt_description_prompt": null,
      "duration": "92.2",
      "negative_tags": null,
      "style_weight": null,
      "weirdness_constraint": null,
      "mv": "chirp-v5"
    }
  ],
  "message": "success",
  "task_id": "c00fc615-dd0a-4fc8-87e0-8a8c4778a71b",
  "platform": "suno",
  "event": "song.completed"
}

5.2 Suno — `event: "song.streaming"`

{
  "code": 200,
  "data": [
    {
      "clip_id": "fe00ce2c-07ed-4f85-86aa-f836effe8127",
      "state": "running",
      "title": "Sunshine Parade",
      "tags": "cheerful, happy, piano-driven with clapping and stomping percussion",
      "lyrics": "[Verse]\nThe sky is wearing its brightest blue hat\nA breeze is dancing where the daisies sat\nFlip-flops slapping on the sunlit track\nNo looking forward\nNo looking back\n\n[Chorus]\nOh we’re marching\nWe’re laughing\nWe’re feeling alive\nIn the sunshine parade\nWhere the good vibes thrive\nClap your hands\nStomp your feet\nLet the joy collide\nThe sunshine parade\nIt’s a happy ride\n\n[Verse 2]\nA squirrel’s got a nut and a grin so wide\nThe river’s humming like it’s on our side\nIce cream melting\nSticky hands collide\nEvery moment's golden\nNo need to hide\n\n[Prechorus]\nThrow your worries in the air\nLet them vanish\nWho knows where\n\n[Chorus]\nOh we’re marching\nWe’re laughing\nWe’re feeling alive\nIn the sunshine parade\nWhere the good vibes thrive\nClap your hands\nStomp your feet\nLet the joy collide\nThe sunshine parade\nIt’s a happy ride\n\n[Bridge]\nEvery step’s a story\nEvery laugh’s a tune\nEven shadows giggle when they meet the moon\nThe world’s a playground\nIt’s a sunny cartoon",
      "image_url": "https://cdn2.suno.ai/image_fe00ce2c-07ed-4f85-86aa-f836effe8127.jpeg",
      "audio_url": "https://audiopipe.suno.ai/?item_id=fe00ce2c-07ed-4f85-86aa-f836effe8127",
      "video_url": null,
      "created_at": "2025-10-18T12:07:42.085Z",
      "gpt_description_prompt": null,
      "duration": null,
      "negative_tags": null,
      "style_weight": null,
      "weirdness_constraint": null,
      "mv": "chirp-v5"
    },
    {
      "clip_id": "bee95b29-15d8-428b-9a1f-086b3ea89361",
      "state": "running",
      "title": "Sunshine Parade",
      "tags": "cheerful, happy, piano-driven with clapping and stomping percussion",
      "lyrics": "[Verse]\nThe sky is wearing its brightest blue hat\nA breeze is dancing where the daisies sat\nFlip-flops slapping on the sunlit track\nNo looking forward\nNo looking back\n\n[Chorus]\nOh we’re marching\nWe’re laughing\nWe’re feeling alive\nIn the sunshine parade\nWhere the good vibes thrive\nClap your hands\nStomp your feet\nLet the joy collide\nThe sunshine parade\nIt’s a happy ride\n\n[Verse 2]\nA squirrel’s got a nut and a grin so wide\nThe river’s humming like it’s on our side\nIce cream melting\nSticky hands collide\nEvery moment's golden\nNo need to hide\n\n[Prechorus]\nThrow your worries in the air\nLet them vanish\nWho knows where\n\n[Chorus]\nOh we’re marching\nWe’re laughing\nWe’re feeling alive\nIn the sunshine parade\nWhere the good vibes thrive\nClap your hands\nStomp your feet\nLet the joy collide\nThe sunshine parade\nIt’s a happy ride\n\n[Bridge]\nEvery step’s a story\nEvery laugh’s a tune\nEven shadows giggle when they meet the moon\nThe world’s a playground\nIt’s a sunny cartoon",
      "image_url": "https://cdn2.suno.ai/image_bee95b29-15d8-428b-9a1f-086b3ea89361.jpeg",
      "audio_url": "https://audiopipe.suno.ai/?item_id=bee95b29-15d8-428b-9a1f-086b3ea89361",
      "video_url": null,
      "created_at": "2025-10-18T12:07:42.085Z",
      "gpt_description_prompt": null,
      "duration": null,
      "negative_tags": null,
      "style_weight": null,
      "weirdness_constraint": null,
      "mv": "chirp-v5"
    }
  ],
  "message": "streaming",
  "task_id": "89a473a3-4ba1-4a5f-9f60-524e8f5c39b3",
  "platform": "suno",
  "event": "song.streaming"
}

5.2 Nuro — `event: "song.completed"`

{
  "task_id": "41627516-89bf-43d7-b437-622e03c8c112",
  "status": "succeeded",
  "progress": 100,
  "audio_url": "https://musicapi-cdn.b-cdn.net/song-41627516-89bf-43d7-b437-622e03c8c112.wav",
  "lyrics": "",
  "duration": 90,
  "genre": "",
  "mood": "",
  "gender": "",
  "timbre": "",
  "prompt": "cinematic background score",
  "theme": "",
  "instrument": "",
  "platform": "nuro",
  "event": "song.completed"
}

5.3 Producer — `event: "song.completed"`

{
  "code": 200,
  "data": [
    {
      "clip_id": "e7118413-bd9d-4c19-a2f0-c950087251cd",
      "title": "Back to You",
      "sound": "emotional pop with gentle piano, warm synths, and a catchy beat",
      "lyrics": "[Verse 1]\nI’ve been running in circles, chasing my doubts\nTrying to quiet the silence that’s been too loud\nEvery streetlight flickers with a memory\nBut none of them shine like you did to me\n[Pre-Chorus]\nAnd I know we said goodbye\nBut it never felt right\nEvery step I take just pulls me back in time\n[Chorus]\nI keep coming back to you\nLike the ocean to the moon\nEvery night I try to move\nBut the stars still spell your name\nI keep falling into you\nNo matter what I do\nThere’s a gravity, a truth\nThat keeps pulling me back to you\n[Verse 2]\nYour voice echoes through the cracks in my soul\nLike a song that I played, then lost control\nTried to dance with strangers, forget the past\nBut every rhythm brings your shadow back\n[Pre-Chorus]\nAnd I swear I’ve tried to change\nRearrange the pain\nBut some love's too deep to ever fade away\n[Chorus]\nI keep coming back to you\nLike the ocean to the moon\nEvery night I try to move\nBut the stars still spell your name\nI keep falling into you\nNo matter what I do\nThere’s a gravity, a truth\nThat keeps pulling me back to you\n[Bridge]\nMaybe we’re just written in the sky\nA little wrong, but still aligned\nAnd even if we break a thousand times\nI’d still come back to make you mine\n[Chorus - Final]\nI keep coming back to you\nLike the ocean to the moon\nEvery night I try to move\nBut the stars still spell your name\nI keep falling into you\nNo matter what I do\nThere’s a gravity, a truth\nThat keeps pulling me back to you\n[Outro]\nBack to you, back to you\nNo matter where I go, I’m back to you",
      "image_url": "https://storage.googleapis.com/corpusant-app-public/riffs/5288569a-a4a1-49b4-a76a-c38a0e6279d3/image/e7118413-bd9d-4c19-a2f0-c950087251cd.jpg",
      "audio_url": "https://storage.googleapis.com/corpusant-app-public/riffs/5288569a-a4a1-49b4-a76a-c38a0e6279d3/audio/e7118413-bd9d-4c19-a2f0-c950087251cd.m4a",
      "video_url": null,
      "created_at": "2025-10-12T13:04:31.589058Z",
      "mv": "FUZZ-2.0",
      "seed": "4246081782",
      "duration": 176.10013605442177,
      "state": "succeeded"
    }
  ],
  "message": "success",
  "task_id": "a335f5ef-ba6c-4c8b-9135-77efa7bf425c",
  "platform": "producer",
  "event": "song.completed"
}

6) Error/Failure Callback (Generic)

On failure, you will receive a payload with event: "song.failed"

Example (generic):

{
  "type": "failed",
  "message": "Task failed. Credits have been refunded.",
  "refund_processed": true,
  "task_id": "49af4269-d1a5-4a61-9139-4497a73caf9d",
  "platform": "producer",
  "event": "song.failed"
}

7) Best Practices

Validate X-Webhook-Signature with the raw body and X-Webhook-Timestamp.

Reject requests whose timestamp drifts beyond a 3–5 minute window.

Use X-Webhook-Id/Idempotency-Key together with (task_id, platform) to deduplicate.

Store task_id at creation time so webhook payloads can be correlated.

Log payloads securely for diagnostics (redact secrets) and prefer HTTPS plus IP/API allowlists.

Last Updated: 2025-10-18

Webhook Integration Guide

🎵 Webhook Integration Guide#

1) Parameters#

webhook_url#

webhook_secret#

2) Delivery Semantics#

3) Security & Verification#

4) Local Testing Utilities#

5) Webhook Payload Examples (Success)#

5.1 Suno — event: "song.completed"#

5.2 Suno — event: "song.streaming"#

5.2 Nuro — event: "song.completed"#

5.3 Producer — event: "song.completed"#

6) Error/Failure Callback (Generic)#

7) Best Practices#