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 by using the API sources in Event Notifications. API sources can be used to send events from your backend applications. You can use this 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, with the datacontenttype attribute value declaring 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 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 should be able to uniquely track this ID in logs and other records. Send unique ID for each send notification. 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 will aid 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 producing 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)

This is the version of 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

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 push notification to an Android device. This is the body that you want to send to FCM server, this must be JSON in string format. For more information regarding FCM body, see here.

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": "{\"en_data\":{\"alert\":\" Password will expire in 10 Days. Please log in to the Bank home page and click on Change Password link to change your password. \", \"android_title\":\"Change Password\"}}"
Binary mode header
ce-ibmenfcmbody: {"en_data":{"alert":" Password will expire in 10 Days. Please log in to the Bank home page and click on Change Password link to change your password. ", "android_title":"Change Password"}}

ibmenapnsbody(string/json)

This attribute is needed if you want to send push notification to an iOS device. This is the body that you want to send to APNs server, this must be JSON in string format. For more information regarding APNs body, follow this documentation here.

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:
"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}}"
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}}

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, you can check out here.

ibmenchromebody(string/json)

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

You can follow these examples for quick start:

"ibmenchromebody": "{\"title\":\"Hello Chrome\", \"options\": {}}"
Binary mode header
ce-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-ibmenchromeheaders: "{"TTL":100}"

ibmenfirefoxbody(string/json)

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

You can follow these examples for quick start:

"ibmenfirefoxbody": "{\"title\":\"Hello Firefox\", \"options\": {}}"
Binary mode header
ce-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-ibmenfirefoxheaders: {"TTL":100, "Urgency": "low" , "Topic": "Test Firefox Notifications"}

"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}}"

####### Binary mode header

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

  • user_id – Useridto be associated with the device. where you want to target your notification
  • tag – This is used to send notifications on registered tags
  • platform - For FCM you can target all registered device by giving platform as "G"
  • 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
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\"]}"

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\"]}"

ibmenpushto: "{\"user_id\": [\" ajay@accts.acmebank.com \",\" ankit@accts.acmebank.com \"]}"**Binary mode header**ce-ibmenpushto: "{\"user_id\": [\"ajay@accts.acmebank.com\",\"ankit@accts.acmebank.com\"]}"

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}}

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, you can check out here.

ibmenchromebody(string/json)

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

You can follow these examples for quick start:

"ibmenchromebody": "{\"title\":\"Hello Chrome\", \"options\": {}}"
Binary mode header
ce-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-ibmenchromeheaders: "{"TTL":100}"
ibmenfirefoxbody(string/json)

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

You can follow these examples for quick start:

"ibmenfirefoxbody": "{\"title\":\"Hello Firefox\", \"options\": {}}"
Binary mode header
ce-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-ibmenfirefoxheaders: {"TTL":100, "Urgency": "low" , "Topic": "Test Firefox Notifications"}
ibmensafaribody(string/json)

This attribute is needed if you want to send push notification to a Safari device. This is the body that you want to send to web server, this must be JSON in string format. For more information regarding Safari body, follow this documentation here.

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"]}}
ibmenpushto(string/json)

This attribute is mandatory for successful delivery from an Android FCM or APNS destination

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

  • user_id – Useridto 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
  • 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
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": "{\"firfox_devices\": [\"3c75972a-37d0-3898-905d-3b5ee0d7c182\",\"L9CACDF5-1EBF-49E1-AD60-E25BA23E994E\"]}"
"ibmenpushto": "{\"safari_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 specific platform.

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