Wallet callbacks

You can register your project to receive callbacks when your audience installs or uninstalls your passes. For Loyalty projects, you can also register to receive callbacks when your audience personalizes their passes.

You can register a callback server using the /project/{project_id}/settings/callback endpoint, providing both the URL you want to call back and any applicable headers required by your callback server.

Wallet Callback Server Requirements

If your callback server requires additional headers, you must provide them when registering your callback. We recommend at least setting an Authorization header. Addresses must be HTTPS.

Your callback server should expect to receive callbacks at up to three endpoints:

  • {baseUrl}/v1/pass/install — Receives a callback when your audience installs passes.
  • {baseUrl}/v1/pass/uninstall — Receives a callback when your audience uninstalls passes.
  • {baseUrl}/v1/pass/{pass_id}/personalize — Receives a callback with a personalization object when your audience personalizes a Loyalty pass. You must add personalization requirements to Apple templates before users can personalize passes created from them.

Wallet Callback Payloads

Your callback server should expect to receive and handle JSON payloads formatted as follows:

Example pass install JSON
{
    "passId": 149440311,
    "templateId": 158327,
    "serialNumber": "3388000000005047792.158327_92a3e4d1-5110-3aca-a26e-fb21618aa5f2_149440311",
    "createdAt": "2020-09-11T22:47:22.000Z",
    "updatedAt": "2020-09-11T22:47:22.000Z",
    "externalId": "coolexample",
    "platform": "android"
}

Example pass uninstall JSON
{
    "passId": 149440311,
    "templateId": 158327,
    "serialNumber": "3388000000005047792.158327_92a3e4d1-5110-3aca-a26e-fb21618aa5f2_149440311",
    "createdAt": "2020-09-11T22:47:22.000Z",
    "updatedAt": "2020-09-11T22:47:22.000Z",
    "externalId": "coolexample",
    "platform": "android"
}

  • passId: Integer, the ID of the pass installed or uninstalled.
  • templateId: Integer, the ID of the template the pass was created from.
  • serialNumber: String, the serial number of the pass. This string is generated by the vendor — Apple or Google.
  • createdAt: String, the date-time when the pass was created.
  • updatedAt: String, the date-time when the pass was last updated.
  • externalId: String, the external ID for the pass, if set.
  • platform: String, the platform on which the pass is installed, one of android or ios.

Register a Wallet Callback Server

You can register your callback server with the /v1/project/{project_id}/settings/callback endpoint. See the Wallet Callbacks API for more information about modifying or deleting a callback specification.

After you register your callback server, Airship will issue callbacks when users install or uninstall passes in your current project.

Register a callback server
POST /v1/project/12345/settings/callback HTTP/1.1
Authorization: Basic <Base64 key>

{
   "baseUrl": "https://www.remotehost.com/callbacks",
   "headers": {
      "Authorization": "Basic dGVzdEB0ZXN0LmNvbTp0ZXN0",
      "Content-Type": "application/json"
   }
}