Contents

Subscribing to notifications

Monitor events for assets, assignments, and users in your organization.

Overview

Notifications make it easy to learn about changes to an organization’s assets, assignments, and users. Using notifications is the simplest way to keep track of the latest events for an organization, such as:

  • Asset count events

  • Asset management events

  • User management events

  • User-associated events

For information about subscribing to different notification types, see ClientConfigRequest.

Each notification has these common fields:

Response field

Description

notificationId

Each notification has a unique ID that you can use for deduping notifications that the server happens to send multiple times.

notificationType

The type of notification. You can use this to determine how to deserialize the notification value.

notification

Contains the JSON object with the changed data. Each notification type has a uniquely structured notification JSON object.

uId

The ID of the location for the notification.

Notifications resemble the following:

{
    "notification": {...},
    "notificationId": "01654971-0d81-467a-9e62-bf8e15e8dabd",
    "notificationType": "ASSET_MANAGEMENT",
    "uId": "2049025000431439"
}

The server delivers notifications on a best-effort basis. The server attempts delivery up to three times over 1–5 minutes. An HTTP 2xx response status from an MDM server indicates a successful notification delivery.

There is a limit of 100 elements in the notification. Any request for more than 100 discrete tasks results in multiple notifications. For example, an assignment request for one adamId to 150 users results in at least two notifications.

If your MDM server doesn’t receive a notification for an event within 5 minutes, check the event status using the Event Status endpoint with the eventId from the original request. While the returned eventStatus is PENDING, wait at least 30 seconds between subsequent status queries to avoid unnecessary load on the server.

Notifications require an HTTPS URL and an authentication token. The authentication token is in a bearer token format. See the ClientConfigRequest for more details about these parameters.

The test notification has the following format:

{
    "notification": {},
    "notificationId": "792e327f-63ea-4658-9aec-f16f4327e3a8",
    "notificationType": "TEST_NOTIFICATION",
    "uId": "2049025000431439"
}

Update asset counts

Update total asset counts upon receiving an ASSET_COUNT notification type that the server sends when:

  • A user buys an asset

  • A user transfers an asset between locations

  • A user refunds an asset

The notifications have the following format:

{
    "notification": {
        "adamId": "408709785",
        "countDelta": -12,
        "pricingParam": "STDQ"
    },
    "notificationId": "4a7801be-53f0-42e1-9505-81c0d1dc9da3",
    "notificationType": "ASSET_COUNT",
    "uId": "2049025000431439"
}

The adamId and pricingParam pair represents the Asset with the count that’s changing, and the countDelta represents the change amount. A positive countDelta indicates an increase; a negative value indicates a decrease.

Update subscription counts

Update subscription seat counts upon receiving a SUBSCRIPTION_COUNT notification type that the server sends when subscription inventory changes — for example, when a content manager purchases additional seats, when seats expire at the end of a billing period, or when renewing seats auto-renew.

The notifications have the following format:

{
    "notification": {
        "parentAdamId": 54321,
        "adamId": 12345,
        "counts": {
            "available": {
                "renewing": 15,
                "expiring": 5
            },
            "total": {
                "renewing": 100,
                "expiring": 20
            }
        }
    },
    "notificationId": "4a7801be-53f0-42e1-9505-81c0d1dc9da3",
    "notificationType": "SUBSCRIPTION_COUNT",
    "uId": "2049025000431439"
}

The notification uses a subset of the SubscriptionCounts schema: the counts object contains only available and total. It omits assigned, which is only present in the synchronous GET /v2/subscriptions response. Use total to track actual seat ownership and available to track unassigned capacity.

Track assignments

Track assignments upon receiving an ASSET_MANAGEMENT notification type that the server sends when it associates or disassociates an asset. The body of the notification contains a list of Assignment objects.

The assignment notifications for associations have the following format:

{
    "notification": {
        "assignments": [
            {
                "adamId": "408709785",
                "pricingParam": "STDQ",
                "serialNumber": "97c42a74-c30e-4172-a65f-6e5a5ba3d477"
            },
            {
                "adamId": "408709785",
                "pricingParam": "STDQ",
                "serialNumber": "495622d3-76f1-4fd3-8647-3f0365159170"
            },
            {
                "adamId": "408709785",
                "pricingParam": "STDQ",
                "serialNumber": "eabcbb89-8213-4185-afb4-30cae931ea37"
            },
            ...
        ],
        "eventId": "87cbc650-16cc-4f9e-a833-e622f377a9f7",
        "result": "SUCCESS",
        "type": "ASSOCIATE"
    },
    "notificationId": "ba8bbb23-44c2-44f6-a928-eff6ba5ffac3",
    "notificationType": "ASSET_MANAGEMENT",
    "uId": "2049025000431439"
}

The assignment notifications for disassociations have the following format:

{
    "notification": {
        "assignments": [
            {
                "adamId": "408709785",
                "clientUserId": "client-100",
                "pricingParam": "STDQ"
            }
        ],
        "eventId": "4bd7371e-6482-4933-8e97-c29f25b7f5f5",
        "result": "SUCCESS",
        "type": "DISASSOCIATE"
    },
    "notificationId": "545e1f6f-ca8b-4e6c-98fe-a7ac3ef63b29",
    "notificationType": "ASSET_MANAGEMENT",
    "uId": "2049025000431439"
}

The assignment notifications for revoke calls have the following format:

{
    "notification": {
        "assignments": [
            {
                "adamId": "408709785",
                "clientUserId": "client-100",
                "pricingParam": "STDQ"
            },
            {
                "adamId": "329103948",
                "clientUserId": "client-100",
                "pricingParam": "STDQ"
            }

        ],
        "eventId": "4bd7371e-6482-4933-8e97-c29f25b7f5f5",
        "result": "SUCCESS",
        "type": "REVOKE"
    },
    "notificationId": "545e1f6f-ca8b-4e6c-98fe-a7ac3ef63b28",
    "notificationType": "ASSET_MANAGEMENT",
    "uId": "2049025000431439"
}

Track subscription assignments

Track subscription assignments upon receiving a SUBSCRIPTION_MANAGEMENT notification type that the server sends when it associates or disassociates a subscription. The body of the notification contains a list of ResponseSubscriptionAssignment objects, each with a renewing Boolean value that reflects the renewal state of the seat assigned to that user.

The subscription assignment notifications for associations have the following format:

{
    "notification": {
        "assignments": [
            {
                "adamId": 12345,
                "clientUserId": "vpp-user",
                "renewing": true
            }
        ],
        "eventId": "c3f990d3-d8c5-41c6-8394-edb1f759a9d2",
        "result": "SUCCESS",
        "type": "ASSOCIATE"
    },
    "notificationId": "7b3c92a1-4e5f-4d8a-b6c7-9e1f2a3b4c5d",
    "notificationType": "SUBSCRIPTION_MANAGEMENT",
    "uId": "2049025000431439"
}

The subscription assignment notifications for disassociations have the following format:

{
    "notification": {
        "assignments": [
            {
                "adamId": 12345,
                "clientUserId": "vpp-user",
                "renewing": true
            }
        ],
        "eventId": "d4ea01e4-e9d6-52d7-9405-f5c2fa6ab0e3",
        "result": "SUCCESS",
        "type": "DISASSOCIATE"
    },
    "notificationId": "8c4d03b2-5f6e-4e9b-a7d8-0f2e3b4c5d6e",
    "notificationType": "SUBSCRIPTION_MANAGEMENT",
    "uId": "2049025000431439"
}

When you set the deferred flag to true in a disassociation request, the notification arrives at the end of the current billing period rather than immediately. For more information about renewal state and deferred disassociation, see Managing subscriptions.

Track user events

Track users upon receiving a USER_MANAGEMENT notification type that the server sends when:

  • Creating a user

  • Updating a user

  • Retiring a user

The notifications for creating a user have the following format:

{
    "notification": {
        "eventId": "e0def1f8-9158-4343-9c52-8dd32da50b9b",
        "result": "SUCCESS",
        "type": "CREATE",
        "users": [
            {
                "clientUserId": "client-100",
                "email": "client-100@apple.com",
                "inviteCode": "f551b37da07146628e8dcbe0111f0364",
                "status": "Registered"
            }
        ]
    },
    "notificationId": "4c0bbb9b-d5a6-4860-83ef-5cf362783c1e",
    "notificationType": "USER_MANAGEMENT",
    "uId": "2049025000431439"
}

The notifications for updating a user have the following format:

{
    "notification": {
        "eventId": "e0def1f8-9158-4343-9c52-8dd32da50b9b",
        "result": "SUCCESS",
        "type": "UPDATE",
        "users": [
            {
                "clientUserId": "client-100",
                "email": "client-100@apple.com",
                "inviteCode": "f551b37da07146628e8dcbe0111f0364",
                "status": "Registered"
            }
        ]
    },
    "notificationId": "5d1ccc7c-e6b7-5971-94fa-6df473894c2f",
    "notificationType": "USER_MANAGEMENT",
    "uId": "2049025000431439"
}

The notifications for retiring a user have the following format:

{
    "notification": {
        "eventId": "e0def1f8-9158-4343-9c52-8dd32da50b9b",
        "result": "SUCCESS",
        "type": "RETIRE",
        "users": [
            {
                "clientUserId": "client-100",
                "email": "client-100@apple.com",
                "inviteCode": "f551b37da07146628e8dcbe0111f0364",
                "status": "Retired"
            }
        ]
    },
    "notificationId": "6e2ddd8d-f7c8-6a82-a50b-7ef584a05d40",
    "notificationType": "USER_MANAGEMENT",
    "uId": "2049025000431439"
}

Track user associations

Track users upon receiving a USER_ASSOCIATED notification type that the server sends when a user accepts an invitation.

The notifications have the following format:

{
    "notification": {
        "associatedUsers": [
            {
                "clientUserId": "client-100",
                "email": "client-100@apple.com",
                "idHash": "leSKk3IaE2vk2KLmv2k3/200D3=",
                "inviteCode": "f551b37da07146628e8dcbe0111f0364",
                "status": "Associated"
            }
        ]
    },
    "notificationId": "90b83144-fb93-4837-9c52-0ae147bdc421",
    "notificationType": "USER_ASSOCIATED",
    "uId": "2049025000431439"
}

See Also

Common tasks