Webhook Payload Format

Every webhook delivery sends a JSON payload via HTTP POST to your configured URL.

Common Payload Structure

{
  "event": "job.completed",
  "jobId": "job_abc123",
  "timestamp": "2026-03-29T10:05:00Z",
  "data": { }
}

Field	Type	Description
event	string	Event type
jobId	string	Related job ID
timestamp	string	ISO 8601 timestamp of the event
data	object	Event-specific payload

Event Types

job.completed

Sent when a split job finishes successfully.

{
  "event": "job.completed",
  "jobId": "job_abc123",
  "timestamp": "2026-03-29T10:05:00Z",
  "data": {
    "status": "completed",
    "splitMode": "duration",
    "segmentCount": 3,
    "totalDuration": 1380,
    "segments": [
      {
        "index": 0,
        "downloadUrl": "https://cdn.audiospliter.com/segments/abc123-0.mp3",
        "duration": 600,
        "size": 9600000,
        "expiresAt": "2026-03-30T10:05:00Z"
      },
      {
        "index": 1,
        "downloadUrl": "https://cdn.audiospliter.com/segments/abc123-1.mp3",
        "duration": 600,
        "size": 9500000,
        "expiresAt": "2026-03-30T10:05:00Z"
      },
      {
        "index": 2,
        "downloadUrl": "https://cdn.audiospliter.com/segments/abc123-2.mp3",
        "duration": 180,
        "size": 2900000,
        "expiresAt": "2026-03-30T10:05:00Z"
      }
    ],
    "metadata": {
      "episodeId": "42"
    }
  }
}

job.failed

Sent when a split job fails.

{
  "event": "job.failed",
  "jobId": "job_abc123",
  "timestamp": "2026-03-29T10:05:00Z",
  "data": {
    "status": "failed",
    "error": {
      "code": "CORRUPT_FILE",
      "message": "Audio file could not be decoded"
    }
  }
}

job.progress

Optional progress updates for large files (sent at 25%, 50%, 75%).

{
  "event": "job.progress",
  "jobId": "job_abc123",
  "timestamp": "2026-03-29T10:03:00Z",
  "data": {
    "status": "processing",
    "progress": 50
  }
}

Request Headers

AudioSpliter includes these headers with every webhook delivery:

Header	Description
Content-Type	application/json
X-AudioSpliter-Signature	HMAC-SHA256 signature for verification
X-AudioSpliter-Event	Event type (e.g., job.completed)
X-AudioSpliter-Delivery	Unique delivery ID
User-Agent	AudioSpliter-Webhook/1.0

Your Endpoint Requirements

Your webhook endpoint must:

1. Accept POST requests with application/json body
2. Return a 2xx status code within 30 seconds
3. Be publicly accessible via HTTPS
4. Verify the signature header (recommended)

Any non-2xx response triggers retry logic.