IBM Cloud Docs
Event Notifications payload

Event Notifications payload

This document outlines the Event Notifications specification.

Introduction

This document describes the payload details for sending events notifications by using the API sources in Event Notifications. API sources can be used to send events from your backend applications. You can use this document to send Push notifications from business backends.

Events from API sources cannot be routed to IBM email and IBM SMS destinations.

`METHOD: POST`
`URL: /event-notifications/v1/apps/{instanceID}/notifications`
`Header: Authorization: Bearer <IAM token>`

The Events adhere to Cloud Event standard. You can find more information about Cloud Events here.

Modes of transport

Event Notifications supports the following two modes to make HTTP calls. This is adhering to the Cloud Events specification.

Binary Mode

In the binary content mode, the value of the event data is placed into the HTTP request, or response, body as-is. The datacontenttype attribute value declares its media type in the HTTP Content-Type header. All other event attributes are mapped to HTTP headers.

All the attribute names are prefixed with ce- and added to the header (except for the data and datacontenttype).

Binary Mode is the recommended way to send notifications.

Structured Mode

In the structured content mode, event metadata attributes and event data are placed into the HTTP request body. For structured mode set the Content-Type header to application/cloudevents+json.

Attributes

CE Mandatory Attributes

The following attributes are mandatory for the event request to be accepted.

ID (String)

A unique identifier that identifies each event. source+id must be unique. The backend shall be able to uniquely track this ID in logs and other records. Send a unique ID for each send notification. The same ID can be sent in case of failure of send notification.

source+id is logged in IBM Cloud Logging service. Using these combination IBM customers are able to trace the event movement from one system to another and aids in debugging and tracing.

Example
id: qwer-1234-1qsd-po94
Binary mode header
ce-id: qwer-1234-1qsd-po94

source (URI-reference)

This is the identifier of the event producer. A way to uniquely identify the source of the event. For IBM Cloud services this is the crn of the service instance that produces the events. For API sources this can be something the event producer backend can uniquely identify itself with.

Example
source: com.mybank.customerbanking.accountmanagement
Binary mode header
ce-source: com.mybank.customerbanking.accountmanagement

specversion (string)

It is the version of the Cloud Events specification that Event Notifications currently supports. This value must be set to "1.0".

Example
specversion:1.0
Binary mode header
ce-specversion:1.0

type (string)

This describes the type of event. It is of the form <event-type-name>:<sub-type>. This type is defined by the producer.

The event type name must be prefixed with the reverse DNS names so the event type is uniquely identified. The same event type can be produced by two different sources. It is highly recommended to use hyphen - as a separator instead of _.

Example 1
`type:com.acmebank.password:expiring-in-15-days`
Type: `com.acmebank.password`
Sub type: `expiring-in-15-days`
Binary mode header
ce-type:com.acmebank.password:expiring-in-15-days`
Example 2
`type:com.acmebank.password-changed`
Type: `com.acmebank.password-changed`
Sub type: N/A
Binary mode header (for Example 2)
`ce-type:com.acmebank.password-changed`

CE optional attributes

The following attributes are optional but highly recommended to take full advantage of Event Notifications.

time (timestamp)

UTC timestamp when the event occurred. Must be in the RFC 3339 format.

Example
time: 2022-02-10T10:51:37+00:00
Binary mode header
ce-time: 2022-02-10T10:51:37+00:00

subject (String)

This is the subject of the event in the event producer (source). So, this can be the account ID of the password that’s about to expire.

Example
subject:ajay@accts.acmebank.com`
Binary mode header
`ce-subject:ajay@accts.acmebank.com`

datacontenttype

Defines the MIME type of the data content. Currently, only "application/json" is supported.

Example
`datacontenttype: application/json`
Binary mode header
`Content-Type:application/json`

data

The payload of the event. This can contain information that can be passed along to destinations like webhooks. Make sure that you are not sending any sensitive information. This must be a valid JSON object.

Example
data: { "lastchanged-days": "74", "reason":"time-based"}

Binary mode – this is part of the HTTP body N/A.

Event Notifications extension mandatory attributes

These are mandatory attributes for every event sent to Event Notifications.

ibmensourceid (string)

This is the ID of the source that is created in Event Notifications. This is available in the Event Notifications UI in the "Sources" section.

Example
ibmensourceid: 121313123:api
Binary mode header
ce-ibmensourceid: 121313123:api

Event Notifications extension optional attributes

These are optional attributes.

ibmenseverity(String)

Some sources can have the concept of an Event severity. Hence a handy way is provided to specify a severity of the event.

Example
ibmenseverity:LOW
Binary mode header
`ce-ibmenseverity:LOW`

ibmendefaultshort(String)

This message is used in case the event that is routed to a destination that needs a human readable text, but a destination-specific attribute is not specified.

For example, if ibmenfcmbody is not specified and the event is routed to Android FCM type destination, ibmendefaultshort is used as the notification title (android_title).

Example
ibmendefaultshort: "Change password"
Binary mode header
ce-ibmendefaultshort: "Change password"

ibmendefaultlong(String)

This message is used in case the event that is routed to a destination that needs a human readable text, but a destination-specific attribute is not specified.

For example, if ibmenfcmbody is not specified and the event is routed to Android FCM type destination, ibmendefaultlong is used as the notification body (alert).

Example
ibmendefaultlong: "Password will expire in 10 Days. Please log in to the Bank home page and click on Change Password link to change your password."
Binary mode header
ce-ibmendefaultlong: "Password will expire in 10 Days. Please log in to the Bank home page and click on Change Password link to change your password."

ibmenfcmbody(string/json)

This attribute is needed if you want to send a push notification to an Android device. This is the body that you want to send to FCM (Firebase Cloud Messaging) server, this must be JSON in string format. For more information regarding the FCM body, see REST Resource: projects.messages.

For compatibility with an earlier version for existing Push notification customers, the previous unified data format is still supported but is deprecated.

Example: Deprecated Push notification service compatible format:
"ibmenfcmbody": "{\"message\":{\"android\":{\"ttl\":\"86400s\",\"notification\":{\"click_action\":\"OPEN_ACTIVITY_1\"},\"data\":{\"id\":\"test_id\"}}}}"
Binary mode header
ce-ibmenfcmbody: {"message":{"android":{"ttl":"86400s","notification":{"click_action":"OPEN_ACTIVITY_1"},"data":{"id":"test_id"}}}}

ibmenapnsbody(string/json)

This attribute is needed if you want to send a push notification to an iOS device. This is the body that you want to send to the APNs (Apple Push Notification Service) server, this must be JSON in string format. For more information regarding APNs body, see Creating the Remote Notification Payload.

For compatibility with an earlier version for existing Push notification customers, the previous unified data format is still supported but is deprecated.

Sample notification payload:
"ibmenapnsbody": {"aps":{"alert":{"title":"Game Request","subtitle":"Five Card Draw","body":"Bob wants to play poker"},"category":"GAME_INVITATION"},"gameID":"12345678"}

To customize your APNs push notifications, you can provide APNs headers. Some of them are mandatory to deliver a notification if key is present. The required body as follows:

"ibmenapnsheaders": "{\"apns-priority\":10, \"apns-collapse-id\": \"collapse\"}"

To get more details on APNs headers, see Generating a remote notification.

Binary mode header
ce-ibmenapnsbody: {"en_data":{"alert":"alert","url":"https","badge":9,"sound":"bingbong.aiff","payload":{"myaarray":["cc75e4a6-edd8-3bec-a7c3-dfca6572a03b"]},"type":"DEFAULT","subtitle":"dummy","title":"dummy1","body":"body","ios_action_key":"key","interactive_category":"interactiveCategory","title_loc_key":"titleLocKey","loc_key":"GAME_PLAY_REQUEST_FORMAT","launch_image":"image.png","title_loc_args":["Shelly","Rick"],"loc_args":["Shelly","Rick"],"attachment_url":"some url","apns_collapse_id":"12","apns_thread_id":"1","apns_group_summary_arg":"apnsGroupSummaryArg","apns_group_summary_arg_count":1}}

ibmenchromebody(string/json)

This attribute is needed if you want to send a push notification to a chrome device. This is the body that you want to send to the FCM server, this must be JSON in string format. For more information regarding chrome body, see Notification.

You can follow these examples for quick start:

"ibmenchromebody": "{\"title\":\"Hello Chrome\", \"options\": {}}"

To customize your chrome push notifications, you can provide chrome headers. Some of them are mandatory to deliver a notification if key is present. The example body as follows:

"ibmenchromeheaders":"{\"TTL\":100}"
Binary mode header
ce-ibmenchromebody: {"title":"Hello Chrome", "options": {}}

ce-ibmenchromeheaders: "{"TTL":100}"

ibmenfirefoxbody(string/json)

This attribute is needed if you want to send a push notification to a Firefox device. This is the body that you want to send to the Firefox Push server, this must be JSON in string format. For more information regarding the Firefox body, see Notification.

You can follow these examples for quick start:

"ibmenfirefoxbody": "{\"title\":\"Hello Firefox\", \"options\": {}}"

To customize your chrome push notifications, you can provide Firefox headers. Some of them are mandatory to deliver a notification if key is present. The example body as follows:

"ibmenfirefoxheaders": "{\"TTL\":100, \"Urgency\": \"low\" , \"Topic\": \"Test Firefox Notifications\"}",
Binary mode header
ce-ibmenfirefoxbody: {"title":"Hello Firefox", "options": {}}

ce-ibmenfirefoxheaders: {"TTL":100, "Urgency": "low" , "Topic": "Test Firefox Notifications"}

ibmensafaribody(string/json)

This attribute is needed if you want to send a push notification to a Safari device. This is the body that you want to send to Apple Push Notification Server, this must be JSON in string format. For more information regarding the Safari body, see Configuring Safari Push Notifications.

You can follow these examples for quick start:

"ibmensafaribody": "{\"aps\":{\"alert\":{\"title\":\"Shipment Order 1832128321 Delevered\",\"body\":\"Shipment Order 1832128321 Delevered.\",\"action\":\"View\"},\"url-args\":[\"1832128321\"]}}"
Binary mode header
ce-ibmensafaribody: {"aps":{"alert":{"title":"Shipment Order 1832128321 Delevered","body":"Shipment Order 1832128321 Delevered.","action":"View"},"url-args":["1832128321"]}}

ibmenhuaweibody(string/json)

This attribute is needed if you want to send a push notification to a Huawei device. This is the body that you want to send to the Huawei Push Kit server, this must be JSON in string format. For more information regarding the Huawei body, see, Huawei Push Notification payload.

You can follow these example for quick start:

"ibmenhuaweibody":"{\"message\":{\"android\":{\"notification\":{\"title\":\"New Message\",\"body\":\"Hello World\",\"click_action\":{\"type\":3}}}}}"
Binary mode header
ce-ibmenhuaweibody: {"aps":{"alert":{"title":"Shipment Order 1832128321 Delevered","body":"Shipment Order 1832128321 Delevered.","action":"View"},"url-args":["1832128321"]}}

ibmenpushto(string/json)

This attribute is mandatory for successful delivery to an Android, FCM, APNS or Huawei destination.

This contains details about the destination where you want to send a push notification. This field is also the string format of JSON and further contains the following field

  • user_id – Userid to be associated with the device. where you want to target your notification
  • tag – This is used to send notifications on registered tags
  • platform - You can target all registered device by platforms.

Following are the corresponding platform values for each type of target.

  • FCM: push_android
  • APNS: push_ios
  • Chrome: push_chrome
  • Firefox: push_firefox
  • Safari: push_safari
  • Huawei : push_huawei
  • fcm_devices – Unique identifier of the FCM device where you want to target your notification
  • apns_devices - Unique identifier of the APNS device where you want to target your notification
  • chrome_devices - Unique identifier of the Chrome Web device where you want to target your notification
  • firefox_devices - Unique identifier of the Firefox Web device where you want to target your notification
  • safari_devices - Unique identifier of the Safari Web device where you want to target your notification
  • huawei_devices - Unique identifier of the Huawei Web device where you want to target your notification
Example
"ibmenpushto": "{\"fcm_devices\": [\"9c75975a-37d0-3898-905d-3b5ee0d7c172\",\"C9CACDF5-6EBF-49E1-AD60-E25BA23E954C\"]}"`
"ibmenpushto": "{\"apns_devices\": [\"1c75972a-37d0-3898-905d-3b5ee0d7c172\",\"M9CACDF5-1EBF-49E1-AD60-E25BA23E954C\"]}"
"ibmenpushto": "{\"chrome_devices\": [\"2c75972a-37d0-3898-905d-3b5ee0d7c182\",\"N9CACDF5-1EBF-49E1-AD60-E25BA23E994D\"]}"
"ibmenpushto": "{\"firefox_devices\": [\"3c75972a-37d0-3898-905d-3b5ee0d7c182\",\"L9CACDF5-1EBF-49E1-AD60-E25BA23E994E\"]}"
"ibmenpushto": "{\"safari_devices\": [\"1175972a-37d0-3898-905d-3b5ee0d7c1D2\",\"Q9CACDF5-1EBF-49E1-AD60-E25BA23E994N\"]}"
"ibmenpushto": "{\"huawei_devices\": [\"1175972a-37d0-3898-905d-3b5ee0d7c1D2\",\"Q9CACDF5-1EBF-49E1-AD60-E25BA23E994N\"]}"

Multiple destinations can be targeted by using following methods

"ibmenpushto": "{\"fcm_devices\": [\"9c75975a-37d0-3898-905d-3b5ee0d7c172\",\"C9CACDF5-6EBF-49E1-AD60-E25BA23E954C\"],\"apns_devices\": [\"1c75972a-37d0-3898-905d-3b5ee0d7c172\",\"M9CACDF5-1EBF-49E1-AD60-E25BA23E954C\"],\"chrome_devices\": [\"2c75972a-37d0-3898-905d-3b5ee0d7c182\",\"N9CACDF5-1EBF-49E1-AD60-E25BA23E994D\"],\"firefox_devices\": [\"3c75972a-37d0-3898-905d-3b5ee0d7c182\",\"L9CACDF5-1EBF-49E1-AD60-E25BA23E994E\"],\"safari_devices\": [\"1175972a-37d0-3898-905d-3b5ee0d7c1D2\",\"Q9CACDF5-1EBF-49E1-AD60-E25BA23E994N\"]}"

Targeting notifications to push user_ids.

"ibmenpushto": "{\"user_ids\": [\"ajay@accts.acmebank.com\",\"ankit@accts.acmebank.com\"]}"

Targeting notifications to push tags.

"ibmenpushto": "{\"tags\": [\"salesTeam\",\"TechTeam\"]}"

Targeting notifications to platforms.

"ibmenpushto": "{\"platforms\":[\"push_android\",\"push_ios\"]]}"

Targeting notifications to a specific platform.

"ibmenpushto": "{\"platforms\":[\"push_android\"]}"
"ibmenpushto": "{\"platforms\":[\"push_ios\"]}"
"ibmenpushto": "{\"platforms\":[\"push_chrome\"]}"
"ibmenpushto": "{\"platforms\":[\"push_firefox\"]}"
"ibmenpushto": "{\"platforms\":[\"push_safari\"]}"
"ibmenpushto": "{\"platforms\":[\"push_huawei\"]}"
Binary mode header
ce-ibmenpushto: "{\"user_id\": [\"ajay@accts.acmebank.com\",\"ankit@accts.acmebank.com\"]}"