AI music API webhook: get a callback when the track is ready

To be called back when a music track is ready, submit to POST /v1/music-router/generate with mode: "webhook" and a public HTTPS webhook_url. Sume sends one signed terminal event, job.completed, job.failed or job.canceled, and no progress events. Keep polling status_url as a backup.

Everything here is from the Webhooks, Music Router and Jobs and results docs, read 2026-09-29.

How do I submit with a webhook?

Webhook URLs must be public HTTPS; localhost, private-network and non-HTTPS URLs are rejected. The submit returns 202 with the job id and polling URLs at once.

curl -X POST https://api.sume.com/v1/music-router/generate \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: music-hook-001" \
  -d '{
    "prompt": "Gentle acoustic ballad, 70 BPM, G major. A 1-minute track. Instrumental, no vocals.",
    "mode": "webhook",
    "webhook_url": "https://example.com/hooks/sume"
  }'

How do I verify the callback?

Sume signs the raw JSON body with HMAC SHA-256 over <timestamp>.<raw_body>. The headers are x-sume-webhook-timestamp and x-sume-webhook-signature: sume-v1=<hex>. During a secret rotation the signature header carries one entry per live secret, so accept the delivery if any sume-v1= entry matches. Reject a timestamp outside your tolerance; the docs suggest five minutes. Read your signing secret from the dashboard Webhooks tab or GET /v1/webhooks/signing-secret, and refuse to verify with an empty secret. The docs give a full TypeScript verifier.

What does delivery guarantee?

Where is the audio in the payload?

The completed event carries a payload.artifacts list like the job result: the audio entry has type audio and a media.sume.com URL. Return any 2xx after storing the event durably, then fetch the file.