1. Home
  2. /Platforms
  3. /Open Channels
  4. /Open Delivery Payload

Open Delivery Payload

Webhook request body examples and details.

Webhook POST Request Body

The request body itself is a JSON object containing a single top level key, "values", pointing to an array of up to 1,000 JSON objects. Airship will break up large pushes into groups of 1,000.

Each object in the array is required to have the following keys:

  • "send_id"—UUID version 4 string. Uniquely identifies the object.
  • "app_key"—22 character string containing the characters: [-_A-Za-z0-9].
  • "payload"—push payload with all "open" overrides for the delivery type applied.
  • "target"—A target object containing the address and a string->string map of alternative identifiers.
Here is an example request body with two objects, each containing all possible keys
POST /hooks/ua/example_hook/push HTTP/1.1
Content-encoding: gzip
Data-Attribute: values
Content-Type: application/vnd.urbanairship+json; version=3

{
   "values": [
      {
         "send_id": "ff76bb85-74bc-4511-a3bf-11b6117784db",
         "app_key": "ZGIwZTY3YjEtZTRiMi00ZG",
         "target": {
            "address": "221B Baker Street",
            "channel_id": "a61448e1-be63-43ee-84eb-19446ba743f0",
            "identifiers": {
               "cid": "1234567",
               "com.example.test_token": "a61448e1-be63-43ee-84eb-19446ba743f0"
            }
         },
         "payload": {
            "alert": "Giant StayPuft Marshmallow Man On a Rampage",
            "title": "Breaking News!",
            "extra": {
               "url": "https://www.example.com/"
            }
         }
      },
      {
         "send_id": "647e799e-3b15-46f0-b4f1-12360d51ce4a",
         "app_key": "ZGIwZTY3YjEtZTRiMi00ZG",
         "target": {
            "address": "1600 Pennsylvania Avenue",
            "channel_id": "5b7e9f63-df28-43f4-8182-b762c628c4c4",
            "identifiers": {
               "cid": "7654321",
               "com.example.test_token": "503640e8-88f7-4dee-9245-7479ac1a8501"
            }
         },
         "payload": {
            "alert": "Giant StayPuft Marshmallow Man On a Rampage",
            "title": "Breaking News!",
            "extra": {
               "url": "https://www.example.com/"
            }
         }
      }
   ]
}
Here is an example request body with one object, containing only the required keys
POST /hooks/ua/example_hook/push HTTP/1.1
Content-encoding: gzip
Data-Attribute: values
Content-Type: application/vnd.urbanairship+json; version=3

{
   "values": [
      {
          "send_id": "ff76bb85-74bc-4511-a3bf-11b6117784db",
          "app_key": "ZGIwZTY3YjEtZTRiMi00ZG",
          "target": {
              "address": "test@example.com",
              "channel_id": "a61448e1-be63-43ee-84eb-19446ba743f0",
          },
          "payload": {
              "alert":"Giant StayPuft Marshmallow Man On a Rampage",
          }
      }
  ]
}

Target Object

Information pertaining to the target related to a webhook payload is defined under the "target" key in each response item.

Target objects are required to have both of following keys:

  • "channel_id"—string, the channel identifier for the target.
  • "address"— string, the customer-provided delivery address for the target.

Target objects may have the following keys:

  • "identifiers"—A JSON object with identifiers specified by the app. Common uses are IDFA or the primary key in your CMS. The values of the keys and values in this object are up to you, however Airship may make additional functionality available using keys prefixed with “com.urbanairship.” so keys using that prefix should be avoided.
Example target object
{
   "identifiers": {
      "com.urbanairship.aaid": "94b0c28e-0f00-4601-af28-e70322f46a75",
      "friend": "ship",
      "ice": "cream",
      "session_id": "5abe6b52-7dcf-4fec-b0a5-d24cb4deaafe",
      "com.urbanairship.limited_ad_tracking_enabled": "false"
   },
   "channel_id": "1e215090-e692-4d89-ab7f-1f2ace2a229b",
   "address": "+1 5558675309"
}

Payload Object

The payload to deliver to the target.

  • "alert"—required, string. The primary message to deliver to the target.
  • "title"—optional, string. The title of the payload. A good example use case would be an email header for an open email notification.
  • "extra"—optional, a string-to-string map of additional values to deliver to the target. Can contain any additional information that users want to deliver to the target.