Contents

Understanding webhook events

Learn the events that describe payloads and the notifications the system sends.

Overview

Webhooks give you real-time, event-driven notifications over HTTP, so you can act on events in an automated way. When you enable a webhook, you get a notification each time one of the events you specify occurs. Use the information in the notification to make subsequent calls to the App Store Connect API to retrieve data.

Webhook events describe the payloads that the system sends to your listening server, based on the configuration you provide when using Create a Webhook Configuration. To read a list of possible webhook event types, see WebhookEventType.

To learn more about setting up, testing, and parsing webhook configurations, see Configuring and parsing App Store Connect API webhook notifications.

Learn webhook event types

The following event types are available. Each type carries a different set of attributes, depending on whether the system notifies you about an app status change, a build change, beta tester feedback, a background asset change, or an alternative marketplace change.

App status changes

Notifications that show when your app changes status, including review states.

Build beta state changes

These notifications show when the external beta build status changes.

Beta feedback

Notifications that show when beta testers report feedback with screenshots or crashes.

Background asset version state changes

These notifications show when your background asset version changes state during processing. The system sends this event after you commit an upload with Commit an Uploaded Asset Pack to a Background Asset Version, when import validation finishes. A change from PROCESSING to FAILED indicates that validation failed; you also receive an email with more context about the failure. For the full list of states, see BackgroundAssetVersionState.

Background asset internal beta releases

These notifications show when the system creates an internal beta release for your background asset version. The system sends this event when import validation succeeds, which confirms that the asset pack processed successfully and that you can submit the version for external beta or App Store review.

Background asset external beta release state changes

These notifications show when your background asset version moves through beta review. A change to REJECTED indicates that review didn’t approve the version, and a change to READY_FOR_TESTING indicates that the version is live for external beta testers. For the full list of states, see BackgroundAssetVersionExternalBetaReleaseState.

Background asset App Store release state changes

These notifications show when your background asset version moves through App Store review. A change to REJECTED indicates that review didn’t approve the version, and a change to READY_FOR_DISTRIBUTION indicates that the version is available to App Store customers. For the full list of states, see BackgroundAssetVersionAppStoreReleaseState.

Build status changes

These notifications show when your build status changes.

Alternative app marketplace changes

These notifications inform a marketplace about changes to apps it distributes.

The system sends a notification for these changes:

  • A new app version is available.

  • You need to remove a specific app version.

  • You need to remove all versions of an app.

Trace background asset events to your API calls

Background asset events correspond to specific points in the upload and review workflow, so you can use them to drive automation instead of polling for state.

To upload a new background asset version, make the following calls:

  1. Create a background asset with Create Asset Pack Record.

  2. Create a background asset version with Create Asset Pack Version Record.

  3. Create a background asset upload file with Create a Reservation for an Asset Pack Upload.

  4. Upload the asset pack to the URLs the previous response returns.

  5. Commit the upload with Commit an Uploaded Asset Pack to a Background Asset Version.

Committing the upload triggers import validation, and the validation result determines which event the system sends. After validation succeeds, submitting the version for review triggers further events:

Event type

The system sends it when

BACKGROUND_ASSET_VERSION_STATE_UPDATED

Import validation fails after you commit the upload. The state changes from PROCESSING to FAILED, and you also receive an email with more context about the failure.

BACKGROUND_ASSET_VERSION_INTERNAL_BETA_RELEASE_CREATED

Import validation succeeds. The asset pack is ready for you to submit for external beta or App Store review.

BACKGROUND_ASSET_VERSION_EXTERNAL_BETA_RELEASE_STATE_UPDATED

Beta review rejects the version, or the version becomes available to external beta testers.

BACKGROUND_ASSET_VERSION_APP_STORE_RELEASE_STATE_UPDATED

App Store review rejects the version, or the version becomes available to App Store customers.

Submit a version for App Store review with Create a Review Submission.

See Also

Essentials