n8n Integration Guide

~10 min

Automate stem separation in your n8n workflows

Prerequisites

StemSplit account with API key
n8n instance (cloud or self-hosted)
Credit balance for processing

What You'll Build

This guide shows you how to create an n8n workflow that:

Submit Jobs

From URLs or uploads

Receive Webhooks

Get notified on completion

Download Results

Process separated stems

Get Your API Key

Log in to StemSplit Settings
Go to API Keys section
Click Create New Key
Name it "n8n Production" and copy the key immediately (it's only shown once)

Set Up n8n Credentials

In n8n, go to Settings → Credentials
Click Add Credential → Header Auth
Configure as follows:

Name	`StemSplit API`
Header Name	`Authorization`
Header Value	`Bearer sk_live_xxxxx`

Create the Submit Job Workflow

Create a workflow that submits audio URLs for stem separation.

Node 1: Trigger (Webhook)

Start your workflow when you POST an audio URL to this webhook.

Webhook node settings

{
  "Path": "process-audio",
  "Method": "POST",
  "Response": "Immediately"
}

Node 2: HTTP Request (Create Job)

Call the StemSplit API to create a separation job.

HTTP Request node settings

{
  "Method": "POST",
  "URL": "https://stemsplit.io/api/v1/jobs",
  "Authentication": "Predefined Credential Type",
  "Credential Type": "Header Auth",
  "Credential": "StemSplit API",
  "Send Headers": true,
  "Header Parameters": {
    "Content-Type": "application/json"
  },
  "Send Body": true,
  "Body Content Type": "JSON",
  "Body": {
    "sourceUrl": "{{ $json.audioUrl }}",
    "outputType": "BOTH",
    "quality": "BEST",
    "outputFormat": "MP3"
  }
}

Node 3: Respond to Webhook

Return the job ID to the caller.

Response

{
  "Respond With": "JSON",
  "Response Body": {
    "success": true,
    "jobId": "{{ $json.id }}",
    "status": "{{ $json.status }}",
    "message": "Job created. You'll receive a webhook when it's done."
  }
}

Set Up Webhook Receiver

Create a separate workflow to receive job completion notifications.

First: Register your webhook URL

Go to Settings → Webhooks and add your n8n webhook URL:

https://your-n8n.example.com/webhook/stemsplit-complete

Node 1: Webhook Trigger

Webhook node settings

{
  "Path": "stemsplit-complete",
  "Method": "POST",
  "Response": "Immediately"
}

Node 2: Verify Signature (Code Node)

Important: Always verify webhook signatures to prevent spoofing.

Code node (JavaScript)

const crypto = require('crypto');

const signature = $input.first().headers['x-webhook-signature'];
const secret = 'whsec_your_secret_here'; // Store in n8n credentials
const payload = JSON.stringify($input.first().json);

const expected = 'sha256=' + crypto
  .createHmac('sha256', secret)
  .update(payload)
  .digest('hex');

if (signature !== expected) {
  throw new Error('Invalid webhook signature');
}

return $input.first();

Node 3: Switch (Route by Event)

Switch node settings

{
  "Mode": "Rules",
  "Rules": [
    {
      "Output": "Completed",
      "Conditions": {
        "String": {
          "Value1": "{{ $json.event }}",
          "Operation": "equals",
          "Value2": "job.completed"
        }
      }
    },
    {
      "Output": "Failed",
      "Conditions": {
        "String": {
          "Value1": "{{ $json.event }}",
          "Operation": "equals",
          "Value2": "job.failed"
        }
      }
    }
  ]
}

Node 4a: Process Completed Jobs

Download the separated stems and save them or send to another service.

HTTP Request node (download vocals)

{
  "Method": "GET",
  "URL": "{{ $json.data.outputs.vocals.url }}",
  "Response Format": "File",
  "Output Binary": true
}

Alternative: Polling Workflow

If webhooks aren't ideal for your setup, you can poll for job status instead.

Polling workflow (Code node)

// Submit job first, then poll
const jobId = $input.first().json.id;
const apiKey = 'sk_live_xxxxx';

async function pollJob() {
  for (let i = 0; i < 60; i++) { // Max 5 minutes
    const response = await fetch(
      `https://stemsplit.io/api/v1/jobs/${jobId}`,
      { headers: { Authorization: `Bearer ${apiKey}` } }
    );
    const job = await response.json();
    
    if (job.status === 'COMPLETED') {
      return job;
    }
    if (job.status === 'FAILED') {
      throw new Error(job.errorMessage || 'Job failed');
    }
    
    // Wait 5 seconds before next poll
    await new Promise(r => setTimeout(r, 5000));
  }
  throw new Error('Job timed out');
}

return [{ json: await pollJob() }];

Test Your Workflow

Activate both workflows in n8n
Send a test request to your submit webhook:

Test request

curl -X POST https://your-n8n.example.com/webhook/process-audio \
  -H "Content-Type: application/json" \
  -d '{"audioUrl": "https://example.com/test-song.mp3"}'

Watch the n8n execution history for both workflows
Check that the separated stems arrive at your completion webhook

Common Use Cases

🎤 Karaoke Generator

Automatically remove vocals from uploaded songs and save instrumentals to cloud storage.

🎧 DJ Sample Library

Extract drums and bass from tracks to build a sample library.

📹 Video Production

Isolate vocals from reference tracks for video editing workflows.

🔊 Podcast Enhancement

Clean up background music to focus on vocal content.

Pro Tips

• Store your API key in n8n credentials, not hardcoded in nodes
• Use error handlers to gracefully handle failed jobs
• Download URLs expire after 1 hour - process them promptly
• Consider using n8n's wait node for simple polling scenarios
• Monitor your credit balance with GET /api/v1/balance

Full API Docs

Complete endpoint reference

Zapier Guide

Alternative automation platform