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

transfer.synced

Managed TransfersDeliveryPOST to your endpoint

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

Sent after a sync run of a synced transfer, when the run has news: every run in planOnly mode (the difference is worked out and nothing is written), a full run that wrote or failed to write something, and a full run that cleared the counts that an earlier planOnly run left. A full run with nothing to do sends nothing.

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.synced
createdAt
date-time
required
data
object
required
data.transferUuid
uuid
required
data.status
string
requiredThe status of the transfer after the run.
data.syncMode
string
requiredfull writes the difference to the destination. planOnly works out the difference and writes nothing.One of: full, planOnly
data.name
string | null
requiredThe name of the first playlist of the transfer.
data.applied
object
requiredWhat the run wrote at the destination.
data.applied.added
number
required
data.applied.removed
number
required
data.applied.moved
number
required
data.applied.failed
number
required
data.pending
object
requiredWhat waits because the run wrote nothing. All zeros in full mode.
data.pending.adds
number
required
data.pending.removals
number
required
data.pending.moves
number
required
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.