Using the notification distribution list

Unsubscribing from the distribution list

To unsubscribe from the distribution list, use the link in the footer of any email that is sent from the distribution list.

Events for notifications

The following table lists the event types that the Notifications service sends to Event Notifications:

Adding an Event Notifications instance to the notification distribution list

Before you can add any Event Notifications instance to the notification distribution list, make sure that you already have an Event Notifications service instance that is in the same account as the distribution list. If you don't have an Event Notifications service instance, see Getting started with Event Notifications. To add an existing Event Notifications service instance to the notification distribution list, complete the following steps:

1. Using the IBM Cloud console, go to Manage > Account > Notification distribution list.
2. Click Add > Event Notifications.
3. Select an Event Notifications service instance from the Event Notifications instance list. If you don't have an Event Notifications service instance that you can connect to your account, you can create one in the IBM Cloud catalog.
4. Click Add.

You cannot add an Event Notifications service instance to the notification distribution list that is already configured.

Sending test notifications to an Event Notifications instance

After you added an Event Notifications instance to your notification distribution list, you can test it out to make sure that the events that are generated by the Notifications service are being forwarded to that instance.

Complete the following steps to send a test notification to an Event Notifications instance:

1. In the IBM Cloud console, go to Manage > Account > Notification distribution list.
2. Select the Event Notifications instance that you want to send a test notification to, and click the Actions icon > Test.
3. Select the notification event type that you want to test, and then click Send test.
   1. To resend the test notification, click Resend test.

Notification payload details

When an Event Notifications instance is added to your account’s distribution list and the account receives a notification, a notification payload is sent to that Event Notifications instance. The payload object properties are the same for all event types. See the following payload example that contains detailed information about a maintenance event for sending a test notification:

{
   "instanceId": "12345678-abcd-1234-efgh-1234567890ab",
   "id": "CHG1234567",
   "source": "crn:v1:bluemix:public:notificationapi::a/<scope>:12345678-abcd-1234-efgh-1234567890ab::",
   "ibmenseverity": "high_impact",
   "severity": "high_impact",
   "ibmensourceid": "crn:v1:bluemix:public:notificationapi::a/<scope>:12345678-abcd-1234-efgh-1234567890ab::",
   "type": "com.ibm.cloud.notificationapi.maintenance",
   "time": "2025-10-08T18:31:09.363Z",
   "ibmendefaultshort": "Maintenance - High Impact: this is a maintenance test notif",
   "ibmendefaultlong": "this is a maintenance test notif \n \nSource ID: CHG1234567 \nType: Maintenance \nSeverity: High Impact \nStart Time: 23 Oct 2025, 7:09 PM UTC \nEnd Time: 24 Oct 2025, 7:09 PM UTC \nUpdate Time: 21 Oct 2025, 2:52 AM UTC \n\nthis is the body text and sev = 1\n\nThis is a test email, please disregard\n\n\n",
   "ibmensmstext": "Maintenance - High Impact: this is a maintenance test notif \nSource ID: CHG2755299 \nCategory: Maintenance \nSeverity: High Impact \n",
   "ibmensubject": "Maintenance - High Impact: this is a maintenance test notif",
   "ibmenhtmlbody": "<div> this is a maintenance test notif</div></br><div><div><b>Source ID:</b> CHG2755299</div><div><b>Type:</b> Maintenance</div><div><b>Severity:</b> High Impact</div><div><b>Start Time:</b> 23 Oct 2025, 7:09 PM UTC</div><div><b>End Time:</b> 24 Oct 2025, 7:09 PM UTC</div><div><b>Update Time:</b> 21 Oct 2025, 2:52 AM UTC</div></br>this is the body text and sev = 1</br></div><div></br><b>This is a test email, please disregard</b></br><div>",
   "specversion": "1.0",
   "datacontenttype": "application/json",
   "data": {
       "sourceID": "CHG1234567",
       "category": "maintenance",
       "severity": 1,
       "crnMasks": [],
       "startTime": "1761246551",
       "endTime": "1761332951",
       "title": [
           {
               "language": "en",
               "text": "this is a maintenance test notif"
           }
       ],
       "body": [
           {
               "content-type": "text/html",
               "language": "en",
               "text": "this is the body text and sev = 1"
           }
       ]
   }
}

Review the following table for more information about the notification's payload properties for Event Notifications.

Deleting an Event Notifications instance

You can delete any Event Notifications instance that you added to the notification distribution list by completing the following steps:

1. Select the Event Notifications service instance that you want to delete from the notification distribution list, and click the Actions icon .
2. Click Delete.

Headers

You receive the payload with a header that you configured in the UI when you added a webhook, and with an additional version header that has a semantic version number. This version header can be used to determine the expected format of the webhook payload.

The current version header is "IBM-Notifications-API-Version": "v2.0.0".

Field values

The following descriptions provide information about the field values that are being sent inside the payload:

body: This field describes the event that is happening on the platform and concerns you. This field contains a detailed, human readable description of the notification and can be several paragraphs long. It can also contain html formatting. This field is configured to support more languages, although only English is supported currently.

category: The type of the event. This can be incident, maintenance, announcement, or security bulletins.

componentNames: If a service is impacted, this field represents it. This can also be a global value like Component: IBM Cloud, not only a specific service. See the services on the IBM Cloud catalog page.

regions: This field shows you the location of the event.

severity: This field refers to the severity of the event. This can be Severity 1, 2, 3 or 4 for incidents, high, medium, or low for maintenance, and major or minor for announcements. See the following detailed severity level descriptions:

* **Incidents**
  * `Severity 1`: Business-critical functionality is inoperable or critical interference failed. This severity usually applies to the production environment and the inability to access services is causing a critical impact on operations.
  * `Severity 2`: Core functionality is impacted. Service is operational but causing major impact on usage.
  * `Severity 3`: Partial or noncritical disruption to functionality with minimal or isolated impact.
  * `Severity 4`: A minor issue that requires action, but does not impact functionality or usage.
* **Maintenance**
  * `High impact`: Maintenance will, or is likely to cause service outages and disruptions.
  * `Medium impact`: Maintenance will, or is likely to cause measurable service degradation but not an actual outage.
  * `Low impact`: Maintenance will cause no service disruption during or after the maintenance window.
* **Announcements**
  * `Major`: Important incidents such as legal notices, service deprecation, or security patches.
  * `Minor`: Informative announcements such as product enhancements.

The severity attribute in the request payload can take on a value of 0, 1, 2, 3, or 4. The following table lists the severity values and their corresponding classifications:

state: This field is only for maintenance and notifications. See the following possible values:

* Values for *Maintenance* states: Planned, In progress, Completed, Canceled, Failed
* Values for *Incident* states: New issue, Investigating, Resolved

title: The title field tells you what the notification is about. This field is configured to support more languages, although only English is supported currently.

startTime, endTime: You can check when the event starts, and when it ends.

The startTime and endTime fields show the start time and end time of the event in Unix Coordinated Universal Time timestamps.

Fields that are sent inside the payload can be either required or optional. Optional fields, for example startTime, are passed if the notification has this type of information, and aren't be passed if the notification does not have it. Required fields, for example category, are passed in all cases. The following table lists which fields are required and which ones are optional:

Additional fields might be added in the future without a major version change. This means that any code that is processing notifications should be prepared to ignore the fields that it does not recognize.

Sending test notifications to a webhook

If you are ready with the previous steps and have a configured webhook, you can test it out easily. Send a test notification to your webhook and make sure that your webhook integration is working correctly and receives the notification.

Complete the following steps to send a test notification to a webhook:

1. Go to Manage > Account > Notification distribution list in the IBM Cloud console.
2. Select the webhook that you would like to send a test notification to, and click the Actions icon .
3. Click Test > Send test.
4. To resend the test notification, click Resend test.