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.

Keys for each object in the array:

  • "send_id" — Required, a UUID version 4 string. Uniquely identifies the object.
  • "app_key" — Required, a 22-character string containing the characters: [-_A-Za-z0-9].
  • "payload" — Required, a push payload with all "open" overrides for the delivery type applied.
  • "target" — Required, a target object containing the address and a string->string map of alternative identifiers.
  • "push_id" — Optional, a UUID version 4 string. Uniquely identifies the push.
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/"
            }
         }
      }
   ]
}
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.

Keys for each target object:

  • "channel_id" — Required, string. The channel identifier for the target.
  • "address" — Required, string. The customer-provided delivery address for the target.
  • "identifiers" — Optional, 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.
  • "opt_in" — Optional, boolean. True if the target has opted in, false otherwise.
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. Possible keys:

  • "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.
  • "summary" — Optional, string. A text summary of the payload contents, as supplied in the push.
  • "media_attachment" — Optional. A URL for an image or video to include with the payload.
  • "interactive" — Optional. An interactive payload object.