Callbacks & WebhooksFree Webhook (0 Credits)Bearer Token AuthBiometric Verification

Voice Validation Phrase Callback

Webhook callback payload specification sent to your server when a custom voice validation phrase is generated. Delivers the dynamic anti-spoofing verification text that the account owner must read aloud to verify authentic identity before cloning.

WEBHOOKWebhook Callback (Your Server)
Test in Playground

When Callbacks Are Sent

The SongMesh API automatically triggers an HTTP POST request to your designated callBackUrl under these events:

  • Phrase Synthesis Complete (status: 'wait_validating'): Dispatched once a unique, randomized anti-spoofing verification phrase is generated and assigned to the task.
  • Voice Verification Timeout / Failure (status: 'failed'): Dispatched if the voice creation session expires or phoneme parsing encounters an error.

Webhook Payload Format

Response Body(200 status)
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "7f8b91c0e24147d3910c4fa891b29a42",
    "validateInfo": "Harmonies fill the air with joyful melodies tonight",
    "status": "wait_validating"
  }
}

Callback Payload Fields

FieldTypeDescription
codeintegerHTTP status code of the webhook delivery (200 = Success, 400/500 = Error).
msgstringStatus message indicating the phrase generation outcome (e.g. "success").
data.taskIdstringUnique identifier of the voice generation task matching the taskId returned by POST /api/v1/createTask.
data.validateInfostringRandomized phonetically balanced validation phrase script (e.g. "Harmonies fill the air with joyful melodies tonight") that the voice owner must read aloud.
data.statusstringCurrent verification stage: "wait_validating" indicates that the phrase has been prepared and the system is waiting for user audio submission.

Receiver Implementation Example

Webhook Receiver
const express = require('express');
const app = express();

app.use(express.json({ limit: '10mb' }));

app.post('/suno-voice-validate-callback', (req, res) => {
  const { code, msg, data } = req.body;

  console.log('Received Suno Voice validation phrase callback:', {
    taskId: data?.taskId,
    status: data?.status,
    message: msg
  });

  if (code === 200 && data?.status === 'wait_validating') {
    console.log('Validation phrase is ready');
    console.log(`Validation phrase: ${data.validateInfo}`);
    // Present phrase to end-user for live vocal recitation
  } else {
    console.error('Validation phrase generation failed:', data?.errorMessage || msg);
  }

  // Always return HTTP 200 within 15 seconds to acknowledge receipt
  return res.status(200).json({ status: 'received' });
});

app.listen(3000, () => {
  console.log('Voice validate callback server running on port 3000');
});

Webhook Security Recommendation

Always verify incoming webhook payloads on your server. Respond with a 200 OK immediately after parsing the payload to prevent redundant delivery retries from the webhook dispatcher.

Anti-Spoofing & Phonetic Verification Workflow

To prevent unauthorized vocal cloning and deepfake abuse, Suno employs dynamic phonetic verification prompts:

Phonetically Balanced Scripts

The validateInfo sentence is generated with diverse vowel and consonant distributions to accurately capture vocal formant frequencies.

Liveness & Consent Confirmation

The user must record themselves speaking the exact sentence. The verification engine confirms acoustic alignment between the phrase audio and the reference singing sample.

Webhook Delivery & Reliability Protocol

Delivery Method
POST (application/json)
Client Response Timeout
15 seconds timeout window
Retry Mechanism
Up to 3 retries on non-200 responses
Status Flag
"wait_validating"

Webhook Receiver Examples

Request Example
// app/api/webhook/suno-voice-validate/route.ts
import { NextRequest, NextResponse } from 'next/server';

interface VoiceValidateCallbackPayload {
  code: number;
  msg: string;
  data: {
    taskId: string;
    validateInfo?: string;
    status: 'wait_validating' | 'failed';
    errorCode?: string | null;
    errorMessage?: string;
  };
}

export async function POST(req: NextRequest) {
  try {
    const payload: VoiceValidateCallbackPayload = await req.json();
    const { code, msg, data } = payload;

    console.log(`[Voice Validate Webhook] Task ${data?.taskId} -> Status: ${data?.status} (Code: ${code})`);

    if (code === 200 && data) {
      if (data.status === 'wait_validating' && data.validateInfo) {
        console.log(`Verification phrase ready for user recitation: "${data.validateInfo}"`);
        // Present validation script to client interface for user recording
      } else {
        console.error(`Validation phrase generation failed: ${data.errorMessage || msg}`);
      }
    } else {
      console.error(`Webhook returned non-200 code: ${code} (${msg})`);
    }

    // Always acknowledge receipt immediately with HTTP 200
    return NextResponse.json({ code: 200, msg: 'success' });
  } catch (error) {
    console.error('Webhook processing error:', error);
    return NextResponse.json({ code: 500, msg: 'Internal server error' }, { status: 500 });
  }
}
Expected Server Acknowledgment(200 status)
{
  "code": 200,
  "msg": "success"
}
Previous EndpointCustom Voice Generation WebhookNext EndpointStem Separation Webhook

Ready to integrate Voice Validation Phrase Callbacks?

Create your free account, obtain your Secret Key, and receive real-time biometric phrase scripts with 5 free generation credits.

Generate Secret Key