Understanding webhook events
Learn how to authenticate and process webhook notifications from Apple Business and the data each event contains.
Overview
Webhooks notify your systems when something changes in your organization so you don’t have to poll the API. When a subscribed event occurs, Apple sends an HTTPS POST with a JSON payload to the URL you specify. When you create or update a webhook, use eventTypes to choose the events it receives. For the available values, see WebhookEventType.
Each notification is a WebhookDelivery that links to a WebhookEvent. The event’s eventType attribute identifies the kind of event, and its payload attribute contains the event data as a JSON string. To review the deliveries for a webhook, see Get All Deliveries for a Webhook. To retry a delivery, see Create a WebhookDelivery.
Set up notification authentication
Secure your webhook by verifying that a request to your endpoint comes from Apple Business. The security protocol for webhooks is hash-based message authentication code (HMAC), which requires that you:
Share a secret phrase with the request sender (Apple Business).
Verify that each POST to your endpoint has the HMAC header and validate it with your secret.
When you create or update a webhook, you define the secret phrase using the secret attribute in WebhookCreateRequest or WebhookUpdateRequest. You need to choose a string value for secret that’s difficult to guess. Apple Business then creates a hash signature using the secret and includes it in each POST. The signature resides in the request header as x-apple-signature. You verify the signature by implementing code in your webhook endpoint that:
Creates a hash from the payload body using your secret.
Compares the hash to the one Apple Business sends in the header to ensure they match.
For example, applying HMAC-SHA256 to the secret “This is my secret” and payload body “Hello, World!” produces this hash:
7f062172b01cb00b53ca068614674a3d982a34062a0f5d37687d5e3377e54657This result verifies a POST is authentic (the sender knows the secret) if the request contains the header:
x-apple-signature: hmacsha256=7f062172b01cb00b53ca068614674a3d982a34062a0f5d37687d5e3377e54657Use an implementation of HMAC hex digest to generate the hash. For more information, see GitHub’s Validating webhook deliveries.
Parse webhook notifications
When Apple Business sends a notification to your webhook, it does so in the form of an HTTP POST. When you receive a notification, check its type to process it accordingly. The action you perform depends on the notification type. Each type has a specific dataset, or schema, composed of attributes that drive the different actions you take. For the types of events and their schemas, see the sections below.
Process a specific notification
This example uses the notification type orgDeviceRelationshipAssignedServerChanged. The attributes include the serial number of the device and the ID of the device management service it’s now assigned to. The payload includes a relationship to the device (instance) and one to the new device management service (newAssignedServer). Use this information to read more about the device using Get Device Information, and about the device management service using Get Device Management Service Information.
{
"data": {
"type": "orgDeviceRelationshipAssignedServerChanged",
"id": "812ada8f-d313-4148-b9db-2f0b50a7b009",
"version": 1,
"attributes": {
"orgDeviceSerialNumber": "XABC123DEF4",
"newMdmServerId": "1F97349736CF4614A94F624E705841AD"
},
"relationships": {
"instance": {
"data": {
"type": "orgDevices",
"id": "XABC123DEF4"
},
"links": {
"self": "https://api-business.apple.com/v1/orgDevices/XABC123DEF4"
}
},
"newAssignedServer": {
"data": {
"type": "mdmServers",
"id": "1F97349736CF4614A94F624E705841AD"
},
"links": {
"self": "https://api-business.apple.com/v1/mdmServers/1F97349736CF4614A94F624E705841AD"
}
}
}
}
}Events
Every event payload has the same structure:
typeis the event type, in a format that matches theeventTypevalue.idis the opaque ID that uniquely identifies the event.versionis the version of the event’s schema.attributescontains the event-specific values.relationshipslinks to the resources the event relates to. Theinstancerelationship always refers to the resource that changed.
Webhook ping
Verify your server is receiving notifications.
After you create a webhook and set up your server to receive notifications, send a test ping to verify that your server is receiving them. Call Create a WebhookPing with a payload like this, where the id for type webhooks is the unique identifier from the response to Create a Webhook, Get Webhooks, or Get Webhook Information:
{
"data": {
"type": "webhookPings",
"relationships": {
"webhook": {
"data": {
"type": "webhooks",
"id": "string"
}
}
}
}
}Apple Business then sends a webhookPingCreated event to the webhook’s URL. You can’t subscribe to this event type, so it doesn’t appear in WebhookEventType. The isPingEvent attribute of the WebhookEvent is true.
Field | Type | Description |
|---|---|---|
| DateTime | The date and time the ping was created. |
{
"data": {
"type": "webhookPingCreated",
"id": "9be761ff-131c-4652-9df8-b779e8adee29",
"version": 1,
"attributes": {
"createdDateTime": "2026-10-14T17:24:54.096092003Z"
}
}
}To check whether the ping reached your server, review the webhook’s past deliveries with Get All Deliveries for a Webhook. Each delivery’s deliveryState is SUCCEEDED, FAILED, or PENDING. If a delivery fails:
errorMessagedescribes the system error when your server returned no HTTP response, such as when the host couldn’t be resolved.response.httpStatusCodeandresponse.bodydescribe your server’s response. Thebodyis present only when the status code isn’t 2xx.
After you fix the problem, use Create a WebhookDelivery to request a redelivery of a past delivery.
Device attribute changed
Event type: ORG_DEVICE_ATTRIBUTE_CHANGED
Sent when an attribute of a device in your organization changes.
Field | Type | Description |
|---|---|---|
| String | The serial number of the device whose attributes changed. |
| Relationship to | The device that changed. |
{
"data": {
"type": "orgDeviceAttributeChanged",
"id": "813ef0fa-ce41-4c3f-88dc-b97096670b26",
"version": 1,
"attributes": {
"orgDeviceSerialNumber": "XABC123DEF4"
},
"relationships": {
"instance": {
"data": {
"type": "orgDevices",
"id": "XABC123DEF4"
},
"links": {
"self": "https://api-business.apple.com/v1/orgDevices/XABC123DEF4"
}
}
}
}
}Device migration details changed
Event type: ORG_DEVICE_ATTRIBUTE_MIGRATION_DETAILS_CHANGED
Sent when the device management service migration details of a device change.
Field | Type | Description |
|---|---|---|
| String | The serial number of the device whose migration details changed. |
| Relationship to | The device that changed. |
{
"data": {
"type": "orgDeviceAttributeMigrationDetailsChanged",
"id": "e00313e9-d0ee-41d4-b13f-f23a23495941",
"version": 1,
"attributes": {
"orgDeviceSerialNumber": "XABC123DEF4"
},
"relationships": {
"instance": {
"data": {
"type": "orgDevices",
"id": "XABC123DEF4"
},
"links": {
"self": "https://api-business.apple.com/v1/orgDevices/XABC123DEF4"
}
}
}
}
}Device assigned server changed
Event type: ORG_DEVICE_RELATIONSHIP_ASSIGNED_SERVER_CHANGED
Sent when the device management service assigned to a device changes.
Field | Type | Description |
|---|---|---|
| String | The serial number of the device whose associated AppleCare coverage changed. |
| String | The ID of the device management service that the device is now assigned to. |
| Relationship to | The device that changed. |
| Relationship to | The device management service that the device is now assigned to. |
{
"data": {
"type": "orgDeviceRelationshipAssignedServerChanged",
"id": "812ada8f-d313-4148-b9db-2f0b50a7b009",
"version": 1,
"attributes": {
"orgDeviceSerialNumber": "XABC123DEF4",
"newMdmServerId": "1F97349736CF4614A94F624E705841AD"
},
"relationships": {
"instance": {
"data": {
"type": "orgDevices",
"id": "XABC123DEF4"
},
"links": {
"self": "https://api-business.apple.com/v1/orgDevices/XABC123DEF4"
}
},
"newAssignedServer": {
"data": {
"type": "mdmServers",
"id": "1F97349736CF4614A94F624E705841AD"
},
"links": {
"self": "https://api-business.apple.com/v1/mdmServers/1F97349736CF4614A94F624E705841AD"
}
}
}
}
}Device warranty changed
Event type: ORG_DEVICE_RELATIONSHIP_WARRANTY_CHANGED
Sent when the AppleCare coverage of a device changes.
Field | Type | Description |
|---|---|---|
| String | The serial number of the device for which an associated AppleCare changed. |
| String | The ID of the AppleCare coverage that changed. |
| Relationship to | The device that changed. |
{
"data": {
"type": "orgDeviceRelationshipWarrantyChanged",
"id": "7de7d1dd-5830-4104-b03e-d861faa1fd1a",
"version": 1,
"attributes": {
"orgDeviceSerialNumber": "XABC123DEF4",
"appleCareCoverageId": "H2WN4ZX7QK"
},
"relationships": {
"instance": {
"data": {
"type": "orgDevices",
"id": "XABC123DEF4"
},
"links": {
"self": "https://api-business.apple.com/v1/orgDevices/XABC123DEF4"
}
}
}
}
}