Skip to the content
Get an API key
  1. API reference
  2. Webhook events

transfer.item_failed

Managed TransfersDeliveryPOST to your endpoint

Sent with the headers X-MusicAPI-Event: transfer.item_failed and X-MusicAPI-Signature: t=<seconds>,v1=<hex HMAC-SHA256 of "t.body">.

Headers

Content-Type

application/json

X-MusicAPI-Event

The event name, for example transfer.completed.

X-MusicAPI-Signature

t=<seconds>,v1=<hex>. The hex is the HMAC-SHA256 of <t>.<raw body> with your endpoint secret.

Payload

id
string
The id of this delivery, evt_<uuid>. A retry sends the same id, so dedupe by it. Two endpoints get two different ids for the same event. Deliveries queued before 2026-10-16 have no id.
event
string
requiredOne of: transfer.item_failed
createdAt
date-time
required
data
object
required
data.transferUuid
uuid
required
data.groupName
string | null
required
data.groupType
string | null
required
data.newlyFailedCount
number
required
data.items
object[]
required
data.items[].name
string
data.items[].artist
string | null
data.items[].error
string | null
data.sourceIntegrationType
string
data.targetIntegrationType
string
data.endUserId
string | null
Your own id for the person: the externalUserId of the session, else the merchantUserId of the source login. Null when you sent neither.
data.batch
TransferWebhookBatch | null
The batch of the transfer. Null for a transfer that was made alone.
data.batch.uuid
uuid
required
data.batch.size
number
requiredHow many transfers the batch holds.
data.batch.endedTransfers
number
requiredHow many of them ended (completed, completed with errors, failed or cancelled).
data.batch.complete
boolean
requiredTrue when every transfer of the batch ended. The event is then the last one of the batch. Two transfers that end at the same moment can both say true, so dedupe your batch notice by uuid.
data.batch.notifyWhenDone
boolean | null
requiredThe notifyWhenDone option of the create call. Null when the call did not send it.
data.batch.completedTransfers
number
requiredThe transfers that ended well (completed or completed with errors).
data.batch.failedTransfers
number
requiredThe transfers that failed or were cancelled.
data.batch.matchedItems
number
requiredThe sum over the transfers that ended well.
data.batch.totalItems
number
requiredThe sum over the transfers that ended well.
data.batch.failedItems
number
requiredThe sum over the transfers that ended well.
data.batch.progress
TransferWebhookBatchProgress
requiredHow far the whole batch got, over every transfer of it (running ones too).
data.batch.progress.processedItems
number
requiredItems processed, summed over every transfer of the batch.
data.batch.progress.totalItems
number
requiredItems to process, summed over every transfer of the batch.
data.batch.progress.pct
number
required0 to 100, rounded down. 100 only when every item was processed.

Delivery and retries

Answer with a 2xx status. We try other answers again, up to 5 attempts in total. The waits between attempts are:

  • 60 s
  • 120 s
  • 240 s
  • 480 s

Set up the endpoint and its secret in the guide Set up and verify.