Webhook Integration

When working with asynchronous processes like music generation, voice cloning, or instrumental extraction, waiting for a task to complete can slow down your workflow. That’s where webhooks come in handy.

Webhooks allow Musicgpt to notify your application the moment a task is completed. You’ll get all the necessary data — including the audio URL — without needing to constantly poll our API.

​

🔧 How It Works

1. Set the webhook_url when submitting your conversion request.
2. Musicgpt will send a POST request to that URL when the task is completed.
3. Your server can then parse the response and proceed with post-processing or user notifications.

​

🧾 Sample Payload

Here’s what a typical webhook payload looks like:

{
  "task_id": "12345678-abcd-1234-efgh-567890abcdef",
  "status": "COMPLETED",
  "status_msg": "Conversion successful",
  "conversion_type": "MUSIC_AI",
  "audio_url": "https://musicgpt.s3.amazonaws.com/audiofile.mp3",
  "title": "Generated Song",
  "conversion_cost": 1.25,
  "createdAt": "2025-01-01T12:00:00Z",
  "updatedAt": "2025-01-01T12:05:00Z"
}

🔗 Set the webhook_url to an endpoint on your server — this is where Musicgpt will notify you once the generation is done.

​

🛡️ Preliminary Response

When you initiate a conversion request, Musicgpt will immediately respond with a preliminary response that includes:

• success: whether the task was successfully initiated
• task_id: a unique ID you can use to track the conversion

Example:

{
  "success": true,
  "task_id": "12345678-abcd-1234-efgh-567890abcdef"
}

This response confirms that the request was accepted. However, the final result (like the downloadable file) will be sent later to your webhook URL.

​

💡 Can’t Use a Webhook?

No problem — if you’re running code on a client device or you don’t have a public server, you can always check the conversion status manually using our helper endpoint:

👉 Get Conversion by ID

​

✅ Why Use Webhooks?

• No need for polling or delays
• Works in the background
• Instantly delivers results
• Ideal for automations and server workflows

Set it once, and let Musicgpt notify you when the magic happens. 🎶