Sign up

background_asset_version_state_updated

Learn about the BACKGROUND_ASSET_VERSION_STATE_UPDATED webhook event. Fired when a background asset version state changes, such as when processing completes.

App Store ConnectBackground Assets
background_asset_version_state_updated

The BACKGROUND_ASSET_VERSION_STATE_UPDATED event fires when the processing state of a background asset version changes. Background assets allow your app to download large content (like game levels, ML models, or media packs) before the user first launches the app.


When does it fire?


This event triggers when a background asset version transitions between processing states — for example, when processing completes successfully or fails. Background assets go through a separate processing pipeline from your app binary.


Payload highlights


The payload includes the app ID, the asset version identifier, and the new processing state. This lets you track when your background assets are ready for distribution alongside your app.


How Yeethook helps


Background asset processing happens asynchronously and can take longer than binary processing. Yeethook notifies your team in Slack or Discord when assets finish processing, so you know when your full app experience is ready for testers.


Common use cases


  • Monitor background asset processing for apps with large downloadable content
  • Get alerts when asset processing fails so you can re-upload
  • Coordinate background asset readiness with app release timing

Example payload

This event uses oldState and newState, and the values describe Apple processing the uploaded asset rather than reviewing it. Apple documents the relationship with id and type sitting directly on instance, without the data wrapper the app version and build events use.

{
  "data": {
    "type": "backgroundAssetVersionStateUpdated",
    "id": "cd7e273b-0514-4bf6-9ccb-30449a7d03e4",
    "attributes": {
      "timestamp": "2026-09-12T14:30:45Z",
      "oldState": "PROCESSING",
      "newState": "FAILED"
    },
    "relationships": {
      "instance": {
        "id": "607fea97-a6ba-445d-a9bd",
        "type": "backgroundAssetVersions",
        "links": {
          "self": "https://api.appstoreconnect.apple.com/v1/backgroundAssetVersions/607fea97-a6ba-445d-a9bd"
        }
      }
    }
  }
}

What it looks like in Slack

Info

Background asset state updated

State change
Processing → Failed

Questions about background_asset_version_state_updated

Why does a failed asset still arrive as an info message?

All four background asset events share one template: a package emoji, info level and a fixed headline. There is no state-to-severity mapping the way there is for app version events, so FAILED and PROCESSING post at the same level and the transition shows up only in the State change row.

Does a p8 key add anything to this event?

No. Yeethook has no enricher for background asset events, so the message is built from the raw payload alone. You get the state change and a link, never the asset name, its size, or the app version it ships with.

Which resource does the event actually point at?

relationships.instance names a backgroundAssetVersions record — the uploaded asset version, not your app and not the App Store version it accompanies. Tying an asset to a release means fetching that record and following it back yourself.

Learn More

Official Apple documentation:

Get this event in Slack or Discord

Connect Yeethook to receive background_asset_version_state_updated notifications in your team's Slack or Discord channels.

Get Started Free