Event Notifications API | IBM Cloud API Docs

Introduction

Last updated: 2023-04-21

IBM Cloud® Event Notifications alerts you to critical events occurring in your IBM Cloud account. You can, in turn send filtered notifications to a set of your users, through a notification channel destination of choice. These users need not be IBM Cloud users.

Send notifications for events of your choice and customize specific events to specific destination channels and user groups. Destinations that are currently supported include:

Email, uses an IBM Cloud provided email service to send emails to your recipients.
Webhooks, send events from supported IBM Cloud services to webhook destinations of your choice.

SDKs

For more information about installation and technical concepts, see the 'README' document in the SDK.

Table 1. List of Event Notifications server, client, and admin SDKs
Admin SDKs	Client SDKs
Go	Android SDK
Node	iOS SDK
Java
Python

IBM Cloud® Event Notifications service provides different APIs that you can use to create and work with your Node.js microservice apps. The API endpoint determines where your Event Notifications actions run and where your app data is stored. By default, all information that is stored in Event Notifications is encrypted in transit and at rest. To ensure disaster recovery, your data is replicated to another location within the same geography. Make sure that your data can be stored in these regions before you start with the Event Notifications service.

The code examples on this tab use the IBM Cloud Event Notifications admin SDK for Go.

Installation

 go get -u github.com/IBM/event-notifications-go-admin-sdk

For more installation options, view this project in GitHub.

Installation

 npm install ibm-event-notifications-node-admin-sdk

For more installation options, view this project in GitHub.

Installation

Maven

<dependency>
    <groupId>com.ibm.cloud</groupId>
    <artifactId>event-notifications</artifactId>
    <version>0.0.2</version>
</dependency>

Gradle

compile 'com.ibm.cloud:event-notifications:0.0.2'

For more installation options, view this project in GitHub.

Installation

 pip install --upgrade "ibm_eventnotifications"

For more installation options, view this project in GitHub.

Endpoint list

The following table contains the base URLs for the Event Notifications API endpoints. When you call the API, use the URL that corresponds to the region where your service instance is deployed. Add the path for each method to form the complete API endpoint for your requests.

Location	API endpoint	Location where Event Notifications actions run	Data is stored in	Data is replicated to
Dallas	Public: `https://us-south.event-notifications.cloud.ibm.com/event-notifications/v1/instances/{guid}` Private: `https://private.us-south.event-notifications.cloud.ibm.com/event-notifications/v1/instances/{guid}`	All Event Notifications actions run in the Dallas (`us-south`) location.	All metadata for the app's features are stored in the Dallas (`us-south`) location.	Data is replicated between three zones within `us-south` for high-availability.
London	Public: `https://eu-gb.event-notifications.cloud.ibm.com/event-notifications/v1/instances/{guid}` Private: `https://private.eu-gb.event-notifications.cloud.ibm.com/event-notifications/v1/instances/{guid}`	All Event Notifications actions run in the London (`eu-gb`) location.	All metadata for the app's features are stored in the London(`eu-gb`) location.	Data is replicated between three zones within `eu-gb` for high-availability.
Sydney	Public: `https://au-syd.event-notifications.cloud.ibm.com/event-notifications/v1/instances/{guid}` Private: `https://private.au-syd.event-notifications.cloud.ibm.com/event-notifications/v1/instances/{guid}`	All Event Notifications actions run in the Sydney (`au-syd`) location.	All metadata for the app's features are stored in the Sydney (`au-syd`) location.	Data is replicated between three zones within au-syd` for high-availability.
Frankfurt	Public: `https://eu-de.event-notifications.cloud.ibm.com/event-notifications/v1/instances/{guid}` Private: `https://private.eu-de.event-notifications.cloud.ibm.com/event-notifications/v1/instances/{guid}`	All Event Notifications actions run in the Frankfurt (`eu-de`) location.	All metadata for the app's features are stored in the Frankfurt (`eu-de`) location.	Data is replicated between three zones within eu-de` for high-availability.

Example request to a Dallas endpoint:

curl -H "Authorization:Bearer {token}" -X  "https://us-south.event-notifications.cloud.ibm.com/event-notifications/v1/instances/{guid}"

Replace {token} in this example with the values for your particular API call.

Authentication

The Event Notifications API uses IBM Cloud Identity and Access Management (IAM) to authenticate requests.

To work with the API, authenticate your application or service by including your IBM Cloud IAM access token in API requests.

To call each method, you need to be assigned a role that includes the required IAM actions. Each method lists the associated action. For more information about IAM actions and how they map to roles, see Managing access for Event Notifications.

IAM authentication. Replace {token} and {url}/{method} with your service credentials.

curl -H "Authorization:Bearer {token}" -X "{url}/{method}"

Authorization: Bearer {token}

For example, if the token is tzLbqWhyALQawBg5TjRIf5sAznhrKQyvBFFaZbtF60m5 in the service credentials, include the credentials in your call like this:

curl -H "Authorization:Bearer {tzLbqWhyALQawBg5TjRIf5sAznhrKQyvBFFaZbtF60m5}" -X "https://us-south.event-notifications.cloud.ibm.com/event-notifications/v1/instances/{guid}"

Example that initializes the SDK programmatically.

import (
	"github.com/IBM/go-sdk-core/v5/core"
    "github.com/IBM/event-notifications-go-admin-sdk/eventnotificationsv1"
)

// IAM API key based authentication
	authenticator := &core.IamAuthenticator{
		ApiKey: <apikey>,
		URL:    <IBM Cloud URL to generate Token>,
	}

	// Set the options for the Event notification instance.
	options := &eventnotificationsv1.EventNotificationsV1Options{
		Authenticator: authenticator,
		URL:           "https://" + region + ".event-notifications.cloud.ibm.com/event-notifications",
	}
	eventNotificationsAPIService, err := eventnotificationsv1.NewEventNotificationsV1(options)
	if err != nil {
		panic(err)
	}

import { EventNotificationsV1 } from 'ibm-event-notifications-node-admin-sdk/event-notifications/v1';
import { IamAuthenticator } from 'ibm-event-notifications-node-admin-sdk/auth';

const authenticator = new IamAuthenticator({
  apikey: <apikey>,
  url: <IBM Cloud URL to generate Token>,
});

const eventNotificationsService = EventNotificationsV1.newInstance({
  authenticator,
  serviceUrl: <service-url>,
});

import com.ibm.cloud.eventnotifications.event_notifications.v1.EventNotifications;

// Create an IAM authenticator.
Authenticator authenticator = new IamAuthenticator.Builder()
				.apikey("<api-key>")
                .build();

// Construct the service client.
EventNotifications eventNotificationsService = new EventNotifications("event_notifications", authenticator);

// Set our custom service URL (optional)
eventNotificationsService.setServiceUrl("https://" + region + ".event-notifications.cloud.ibm.com/event-notifications");

from ibm_eventnotifications import EventNotificationsV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

# Create an IAM authenticator.
authenticator = IAMAuthenticator('<api-key>')

# Construct the service client.
event_notifications_service = EventNotificationsV1(authenticator=authenticator)

# Set our custom service URL (optional)
event_notifications_service.set_service_url(<service-url>)

Error handling

This API uses standard HTTP response codes to indicate whether a method completed successfully. A 2xx response indicates success. A 4xx type response is some sort of failure, and a 5xx type response usually indicates an internal system error.

HTTP status code	Description	Recovery
`200`	Success	The request was successful.
`201`	Success	The resource was successfully created and added to your IBM Cloud account.
`400`	Bad request	The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request.
`401`	Unauthorized	You are not authorized to make this request. Log in to IBM Cloud and try again. If this error persists, contact the account owner to check your permissions.
`403`	Forbidden	The supplied authentication is not authorized to access the apps. Check that you have the correct access credentials and permissions.
`404`	Not found	The requested resource could not be found.
`408`	Request timeout	The connection to the server timed out. Wait a few minutes, then try again.
`409`	Conflict	The entity is already in the requested state.
`415`	Unsupported media type	The server refuses the request because the payload format is in an unsupported format.
`429`	Too many requests	Rate limit is 1000 calls per second. Wait before calling the API again.
`500`	Internal server error	IBM Cloud Event Notifications is not available. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
`503`	Service temporarily unavailable	IBM Cloud Event Notifications could not process the request, due to a temporary overloading or maintenance. Try to reduce your request rate, or retry after a few minutes. If the error persists, contact IBM Cloud support.

Example error handling

import (
	    "github.com/IBM/go-sdk-core/v5/core"
    eventnotificationsv1 "github.com/IBM/event-notifications-go-admin-sdk/eventnotificationsv1"
)
	// Set the options for the Event notification instance.
	options := &eventnotificationsv1.EventNotificationsV1Options{options}
	eventNotificationsInstance, err := eventnotificationsv1.NewEventNotificationsV1(options)
	// Check for errors
if err != nil {
  panic(err)
}

Auditing

You can monitor API activity within your account. Whenever an API method is called, an event is generated that you can then track and audit. The specific event type is listed for each method that generates auditing events. For methods that don't list any events, no events are generated.

For more information about how to track Event Notifications activity, see Auditing events for Event Notifications.

Send Notifications body from the instance. For more information about Event Notifications payload, see here.

POST /v1/instances/{instance_id}/notifications

(eventNotifications *EventNotificationsV1) SendNotifications(sendNotificationsOptions *SendNotificationsOptions) (result *NotificationResponse, response *core.DetailedResponse, err error)

(eventNotifications *EventNotificationsV1) SendNotificationsWithContext(ctx context.Context, sendNotificationsOptions *SendNotificationsOptions) (result *NotificationResponse, response *core.DetailedResponse, err error)

sendNotifications(params)

send_notifications(self,
        instance_id: str,
        *,
        body: 'NotificationCreate' = None,
        **kwargs
    ) -> DetailedResponse

ServiceCall<NotificationResponse> sendNotifications(SendNotificationsOptions sendNotificationsOptions)

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

event-notifications.notification.create

Auditing

Calling this method generates the following auditing event.

event-notifications.notification.create

Request

Instantiate the SendNotificationsOptions struct and set the fields to provide parameter values for the SendNotifications method.

Use the SendNotificationsOptions.Builder to create a SendNotificationsOptions object that contains the parameter values for the sendNotifications method.

Path Parameters

instance_id
Required*
string
Unique identifier for IBM Cloud Event Notifications instance

Possible values: 10 ≤ length ≤ 256, Value must match regular expression [a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]

Request Body

NotificationCreate

Payload describing a notification create request

Examples:

View

parameter

WithContext method only

SendNotificationsOptions

The SendNotifications options.

parameters

instanceId
Required*
string
Unique identifier for IBM Cloud Event Notifications instance.

Possible values: 10 ≤ length ≤ 256, Value must match regular expression /[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]/
body
Payload describing a notification create request.

Examples:
View

parameters

instance_id
Required*
str
Unique identifier for IBM Cloud Event Notifications instance.

Possible values: 10 ≤ length ≤ 256, Value must match regular expression /[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]/
body
Payload describing a notification create request.

Examples:
View

SendNotificationsOptions

The sendNotifications options.

Example request

curl -X POST --location --header "Authorization: Bearer {iam_token}"   --header "Content-Type: application/json"   "{base_url}/v1/instances/{instance_id}/notifications"

Example request

notificationCreateModel := &eventnotificationsv1.NotificationCreate{}

notificationCreateModel.Ibmenseverity = &notificationSeverity
notificationCreateModel.ID = &notificationID
notificationCreateModel.Source = &notificationsSouce
notificationCreateModel.Ibmensourceid = &sourceID
notificationCreateModel.Type = &typeValue
notificationCreateModel.Time = &strfmt.DateTime{}
notificationCreateModel.Specversion = &specVersion

notificationDevicesModel := "{\"user_ids\": [\"userId\"]}"
notificationSafariBodyModel := "{\"en_data\": {\"alert\": \"Alert message\"}}"

notificationCreateModel.Ibmenpushto = &notificationDevicesModel

apnsOptions := map[string]interface{}{
  "aps": map[string]interface{}{
    "alert": "APNS alert",
    "badge": 5,
  },
}

ibmenapnsbody, _ := json.Marshal(apnsOptions)
ibmenapnsbodyString := string(ibmenapnsbody)

fcmOptions := map[string]interface{}{
  "notification": map[string]interface{}{
    "title": "FCM alert",
    "body":  "alert message for FCM",
  },
}
ibmenfcmbody, _ := json.Marshal(fcmOptions)
ibmenfcmbodyString := string(ibmenfcmbody)

apnsHeaders := map[string]interface{}{
  "apns-collapse-id": "collapse-id",
}
ibmenapnsheaderbody, _ := json.Marshal(apnsHeaders)
ibmenapnsheaderstring := string(ibmenapnsheaderbody)

notificationCreateModel.Ibmenfcmbody = &ibmenfcmbodyString
notificationCreateModel.Ibmenapnsbody = &ibmenapnsbodyString
notificationCreateModel.Ibmenapnsheaders = &ibmenapnsheaderstring
notificationCreateModel.Ibmensafaribody = &notificationSafariBodyModel
notificationCreateModel.Ibmendefaultshort = core.StringPtr("This is simple test alert from IBM Cloud Event Notifications service.")
notificationCreateModel.Ibmendefaultlong = core.StringPtr("Hi, we are making sure from our side that the service is available for consumption.")

sendNotificationsOptionsModel := new(eventnotificationsv1.SendNotificationsOptions)
sendNotificationsOptionsModel.InstanceID = &instanceID
sendNotificationsOptionsModel.Body = notificationCreateModel

notificationResponse, response, err := eventNotificationsService.SendNotifications(sendNotificationsOptionsModel)

if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(notificationResponse, "", "  ")
fmt.Println(string(b))


notificationCreateModel := &eventnotificationsv1.NotificationCreate{}

notificationCreateModel.Ibmenseverity = &notificationSeverity
notificationCreateModel.ID = &notificationID
notificationCreateModel.Source = &notificationsSouce
notificationCreateModel.Ibmensourceid = &sourceID
notificationCreateModel.Type = &typeValue
notificationCreateModel.Time = &strfmt.DateTime{}
notificationCreateModel.Specversion = &specVersion
notificationCreateModel.Ibmendefaultshort = core.StringPtr("Offer Alert")
notificationCreateModel.Ibmendefaultlong = core.StringPtr("Alert on expiring offers")

notificationDevicesModel := "{\"user_ids\": [\"userId\"]}"

notificationCreateModel.Ibmenpushto = &notificationDevicesModel

apnsOptions := map[string]interface{}{
  "aps": map[string]interface{}{
    "alert": "alert message",
    "badge": 5,
  },
}

ibmenapnsbody, _ := json.Marshal(apnsOptions)
ibmenapnsbodyString := string(ibmenapnsbody)

fcmOptions := map[string]interface{}{
  "notification": map[string]interface{}{
    "title": "alert title",
    "body":  "alert message",
  },
}
ibmenfcmbody, _ := json.Marshal(fcmOptions)
ibmenfcmbodyString := string(ibmenfcmbody)

apnsHeaders := map[string]interface{}{
  "apns-collapse-id": "collapse-id",
}
ibmenapnsheaderbody, _ := json.Marshal(apnsHeaders)
ibmenapnsheaderstring := string(ibmenapnsheaderbody)

notificationCreateModel.Ibmenfcmbody = &ibmenfcmbodyString
notificationCreateModel.Ibmenapnsbody = &ibmenapnsbodyString
notificationCreateModel.Ibmenapnsheaders = &ibmenapnsheaderstring

sendNotificationsOptionsModel := new(eventnotificationsv1.SendNotificationsOptions)
sendNotificationsOptionsModel.InstanceID = &instanceID
sendNotificationsOptionsModel.Body = notificationCreateModel

notificationResponse, response, err := eventNotificationsService.SendNotifications(sendNotificationsOptionsModel)

if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(notificationResponse, "", "  ")
fmt.Println(string(b))

Example request

// NotificationFCMDevices
const notificationFcmDevicesModel = {
  user_ids: [userId],
};

const notificationApnsBodyModel = {
  aps: {
    alert: 'Game Request',
    badge: 5,
  },
};

const notificationFcmBodyModel = {
  notification: {
    title: 'Portugal vs. Denmark',
    badge: 'great match!',
  },
};

const apnsHeaders = {
  'apns-collapse-id': '123',
};

const notificationSafariBodymodel = {
  saf: {
    alert: 'Game Request',
    badge: 5,
  },
};

const notificationCreateModel = {
  instanceId,
  ibmenseverity: notificationSeverity,
  id: notificationID,
  source: notificationsSouce,
  ibmensourceid: sourceId,
  type: typeValue,
  time: date,
  ibmenpushto: JSON.stringify(notificationFcmDevicesModel),
  ibmenfcmbody: JSON.stringify(notificationFcmBodyModel),
  ibmenapnsbody: JSON.stringify(notificationApnsBodyModel),
  ibmensafaribody: JSON.stringify(notificationSafariBodymodel),
  ibmendefaultshort: 'testString',
  ibmendefaultlong: 'testString',
  specversion: '1.0',
};

const body = notificationCreateModel;
const sendNotificationsParams = {
  instanceId,
  body,
};

let res;
try {
  res = await eventNotificationsService.sendNotifications(sendNotificationsParams);
} catch (err) {
  console.warn(err);
}

Example request

String notificationDevices = "{\"user_ids\": [\"userId\"]}";
String fcmJsonString = "{ \"title\" : \"Portugal vs. Denmark\", \"badge\": \"great match\" }";
String apnsJsonString = "{\"alert\": \"Game Request\", \"badge\": 5 }";
String safariJsonString = "{\"aps\":{\"alert\":{\"title\":\"FlightA998NowBoarding\",\"body\":\"BoardinghasbegunforFlightA998.\",\"action\":\"View\"},\"url-args\":[\"boarding\",\"A998\"]}}";

NotificationCreate body = new NotificationCreate.Builder()
        .id(instanceId)
        .ibmenseverity("MEDIUM")
        .id("FCM ID")
        .source(sourceId)
        .ibmensourceid(sourceId)
        .type("com.acme.offer:new")
        .time(new java.util.Date())
        .ibmenpushto(notificationDevices)
        .ibmenfcmbody(fcmJsonString)
        .ibmenapnsbody(apnsJsonString)
        .ibmensafaribody(safariJsonString)
        .ibmendefaultshort("Match Info")
        .ibmendefaultlong("Portugal lead the group with a 2-0 win")
        .specversion("1.0")
        .build();

SendNotificationsOptions sendNotificationsOptions = new SendNotificationsOptions.Builder()
        .instanceId(instanceId)
        .body(body)
        .build();

Response<NotificationResponse> response = eventNotificationsService.sendNotifications(sendNotificationsOptions).execute();
NotificationResponse notificationResponse = response.getResult();

System.out.println(notificationResponse);

Example request

notification_devices_model = {
  'user_ids': ['userId'],
}

notification_apns_body_model = {
  "aps": {
    "alert": "Game Request",
    "badge": 5,
  },
}
notification_fcm_body_model = {
  "notification": {
    "title": "Portugal vs. Denmark",
    "body": "great match!",
  },
}

message_apns_headers = {
  "apns-collapse-id": "123",
}

notificationSafariBodymodel = {
  'saf': {
    'alert': 'Game Request',
    'badge': 5,
  },
}

notification_create_model = {
  'ibmenseverity': notification_severity,
  'ibmenfcmbody': json.dumps(notification_fcm_body_model),
  'ibmenpushto': json.dumps(notification_devices_model),
  'ibmenapnsbody': json.dumps(notification_apns_body_model),
  'ibmensourceid': source_id,
  'ibmendefaultshort': 'teststring',
  'ibmendefaultlong': 'teststring',
  'ibmensafaribody': json.dumps(notificationSafariBodymodel),
  'id': notification_id,
  'source': notifications_source,
  'type': type_value,
  'specversion': '1.0',
  'time': '2019-01-01T12:00:00.000Z',
}

send_notifications_response = event_notifications_service.send_notifications(
  instance_id,
  body=notification_create_model
).get_result()

print(json.dumps(send_notifications_response, indent=2))

Response

Response Body

NotificationResponse

Payload describing a notifications response

NotificationResponse

Payload describing a notifications response.

Examples:

View

NotificationResponse

Payload describing a notifications response.

Examples:

View

NotificationResponse

Payload describing a notifications response.

Examples:

View

NotificationResponse

Payload describing a notifications response.

Examples:

View

Status Code

202
New notification created successfully
400
Bad or incorrect request body
401
Trying to access the API with unauthorized token
415
Request body type is not application/json
500
Internal server error
default
Unexpected Error

Example responses

Status 202

{
  "notification_id": "09463a26-64b7-412b-85de-dbad730e9230"
}

Success example

{
  "notification_id": "09463a26-64b7-412b-85de-dbad730e9230"
}

Status 400

{
  "trace": "11a35929-7cb8-4f06-bd64-abe9c391b06d",
  "status_code": 400,
  "errors": [
    {
      "code": "incorrect_json",
      "message": "Required JSON parameters missing or incorrect",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Error example

{
  "trace": "11a35929-7cb8-4f06-bd64-abe9c391b06d",
  "status_code": 400,
  "errors": [
    {
      "code": "incorrect_json",
      "message": "Required JSON parameters missing or incorrect",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Status 401

{
  "trace": "c327fb84-bd47-4726-9946-01f6ecb29734",
  "status_code": 401,
  "errors": [
    {
      "code": "unauthorized",
      "message": "User authorization failed",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-authentication"
    }
  ]
}

Error example

{
  "trace": "c327fb84-bd47-4726-9946-01f6ecb29734",
  "status_code": 401,
  "errors": [
    {
      "code": "unauthorized",
      "message": "User authorization failed",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-authentication"
    }
  ]
}

Status 415

{
  "trace": "abecd699-bcf4-4298-9cd0-a88bbf1d18c9",
  "status_code": 415,
  "errors": [
    {
      "code": "media_type_error",
      "message": "Content-Type header is wrong",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Error example

{
  "trace": "abecd699-bcf4-4298-9cd0-a88bbf1d18c9",
  "status_code": 415,
  "errors": [
    {
      "code": "media_type_error",
      "message": "Content-Type header is wrong",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Status 500

{
  "trace": "abecd699-bcf4-4298-9cd0-a88bbf1d18c9",
  "status_code": 500,
  "errors": [
    {
      "code": "cnfser01",
      "message": "Unexpected internal server error",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Error example

{
  "trace": "abecd699-bcf4-4298-9cd0-a88bbf1d18c9",
  "status_code": 500,
  "errors": [
    {
      "code": "cnfser01",
      "message": "Unexpected internal server error",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Status default

{
  "trace": "abecd699-bcf4-4298-9cd0-a88bbf1d18c9",
  "status_code": 500,
  "errors": [
    {
      "code": "cnfser01",
      "message": "Unexpected internal server error",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Error example

{
  "trace": "abecd699-bcf4-4298-9cd0-a88bbf1d18c9",
  "status_code": 500,
  "errors": [
    {
      "code": "cnfser01",
      "message": "Unexpected internal server error",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Create a new API Source

Create a new API Source.

POST /v1/instances/{instance_id}/sources

(eventNotifications *EventNotificationsV1) CreateSources(createSourcesOptions *CreateSourcesOptions) (result *SourceResponse, response *core.DetailedResponse, err error)

(eventNotifications *EventNotificationsV1) CreateSourcesWithContext(ctx context.Context, createSourcesOptions *CreateSourcesOptions) (result *SourceResponse, response *core.DetailedResponse, err error)

createSources(params)

create_sources(self,
        instance_id: str,
        name: str,
        description: str,
        *,
        enabled: bool = None,
        **kwargs
    ) -> DetailedResponse

ServiceCall<SourceResponse> createSources(CreateSourcesOptions createSourcesOptions)

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

event-notifications.sources.create

Auditing

Calling this method generates the following auditing event.

event-notifications.sources.create

Request

Instantiate the CreateSourcesOptions struct and set the fields to provide parameter values for the CreateSources method.

Use the CreateSourcesOptions.Builder to create a CreateSourcesOptions object that contains the parameter values for the createSources method.

Path Parameters

instance_id
Required*
string
Unique identifier for IBM Cloud Event Notifications instance

Possible values: 10 ≤ length ≤ 256, Value must match regular expression [a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]

Request Body

Required*

SourceCreate

Source object

Examples:

View

parameter

WithContext method only

CreateSourcesOptions

The CreateSources options.

parameters

instanceId
Required*
string
Unique identifier for IBM Cloud Event Notifications instance.

Possible values: 10 ≤ length ≤ 256, Value must match regular expression /[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]/
name
Required*
string
Name of the source.

Possible values: 1 ≤ length ≤ 255, Value must match regular expression /[a-zA-Z 0-9-_\/.?:'\";,+=!#@$%^&*()]*/
description
Required*
string
Description of the source.

Possible values: 1 ≤ length ≤ 255, Value must match regular expression /[a-zA-Z 0-9-_\/.?:'\";,+=!#@$%^&*()]*/
enabled
boolean
Whether the source is enabled or not.

Default: true

parameters

instance_id
Required*
str
Unique identifier for IBM Cloud Event Notifications instance.

Possible values: 10 ≤ length ≤ 256, Value must match regular expression /[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]/
name
Required*
str
Name of the source.

Possible values: 1 ≤ length ≤ 255, Value must match regular expression /[a-zA-Z 0-9-_\/.?:'\";,+=!#@$%^&*()]*/
description
Required*
str
Description of the source.

Possible values: 1 ≤ length ≤ 255, Value must match regular expression /[a-zA-Z 0-9-_\/.?:'\";,+=!#@$%^&*()]*/
enabled
bool
Whether the source is enabled or not.

Default: true

CreateSourcesOptions

The createSources options.

Example request

curl -X POST --location --header "Authorization: Bearer {iam_token}"   --header "Content-Type: application/json"   --data '{"name":"Event Notification Create Source Acme","description":"This source is used for Acme Bank","enabled":true}'   "{base_url}/v1/instances/{instance_id}/sources"

Example request

createSourcesOptions := eventNotificationsService.NewCreateSourcesOptions(
  instanceID,
  "Event Notification Create Source Acme",
  "This source is used for Acme Bank",
)
createSourcesOptions.SetEnabled(false)

sourceResponse, response, err := eventNotificationsService.CreateSources(createSourcesOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(sourceResponse, "", "  ")
fmt.Println(string(b))

Example request

const params = {
  instanceId,
  name: 'Event Notification Create Source Acme',
  description: 'This source is used for Acme Bank',
  enabled: false,
};

let res;
try {
  res = await eventNotificationsService.createSources(params);
  console.log(JSON.stringify(res.result, null, 2));
  sourceId = res.result.id;
} catch (err) {
  console.warn(err);
}

Example request

CreateSourcesOptions createSourcesOptions = new CreateSourcesOptions.Builder()
        .instanceId(instanceId)
        .name("Event Notification Create Source Acme")
        .description("This source is used for Acme Bank")
        .enabled(false)
        .build();

Response<SourceResponse> response = eventNotificationsService.createSources(createSourcesOptions).execute();
SourceResponse sourceResponse = response.getResult();

System.out.println(sourceResponse);

Example request

source_response = event_notifications_service.create_sources(
  instance_id,
  name='Event Notification Create Source Acme',
  description='This source is used for Acme Bank',
  enabled=False
).get_result()

print(json.dumps(source_response, indent=2))

Response

Response Body

SourceResponse

Payload describing a source

SourceResponse

Payload describing a source.

Examples:

View

SourceResponse

Payload describing a source.

Examples:

View

SourceResponse

Payload describing a source.

Examples:

View

SourceResponse

Payload describing a source.

Examples:

View

Status Code

201
Response body after source creation
400
Bad or incorrect request body
401
Trying to access the API with unauthorized token
404
Requested resource not found
409
Trying to create duplicate source
415
Request body type is not application/json
500
Internal server error
default
Unexpected Error

Example responses

Status 201

{
  "id": "00bb34e5-b8c1-4159-af15-8bc6980c3ab2:api",
  "name": "CloudEvents Source",
  "description": "This source is related to cloud events",
  "enabled": false,
  "created_at": "2021-09-14T20:43:47.484072Z"
}

Success example

{
  "id": "00bb34e5-b8c1-4159-af15-8bc6980c3ab2:api",
  "name": "CloudEvents Source",
  "description": "This source is related to cloud events",
  "enabled": false,
  "created_at": "2021-09-14T20:43:47.484072Z"
}

Status 400

{
  "trace": "11a35929-7cb8-4f06-bd64-abe9c391b06d",
  "status_code": 400,
  "errors": [
    {
      "code": "incorrect_json",
      "message": "Required JSON parameters missing or incorrect",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Error example

{
  "trace": "11a35929-7cb8-4f06-bd64-abe9c391b06d",
  "status_code": 400,
  "errors": [
    {
      "code": "incorrect_json",
      "message": "Required JSON parameters missing or incorrect",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Status 401

{
  "trace": "c327fb84-bd47-4726-9946-01f6ecb29734",
  "status_code": 401,
  "errors": [
    {
      "code": "unauthorized",
      "message": "User authorization failed",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-authentication"
    }
  ]
}

Error example

{
  "trace": "c327fb84-bd47-4726-9946-01f6ecb29734",
  "status_code": 401,
  "errors": [
    {
      "code": "unauthorized",
      "message": "User authorization failed",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-authentication"
    }
  ]
}

Status 404

{
  "trace": "208fddf2-dd25-481d-b180-809422a1b5ac",
  "status_code": 404,
  "errors": [
    {
      "code": "not_found",
      "message": "Requested resource not found",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Error example

{
  "trace": "208fddf2-dd25-481d-b180-809422a1b5ac",
  "status_code": 404,
  "errors": [
    {
      "code": "not_found",
      "message": "Requested resource not found",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Status 409

{
  "trace": "9e948d31-a5be-42be-9dc1-a1006ba9d542",
  "status_code": 409,
  "errors": [
    {
      "code": "source_conflict",
      "message": "Duplicate source name",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Error example

{
  "trace": "9e948d31-a5be-42be-9dc1-a1006ba9d542",
  "status_code": 409,
  "errors": [
    {
      "code": "source_conflict",
      "message": "Duplicate source name",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Status 415

{
  "trace": "abecd699-bcf4-4298-9cd0-a88bbf1d18c9",
  "status_code": 415,
  "errors": [
    {
      "code": "media_type_error",
      "message": "Content-Type header is wrong",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Error example

{
  "trace": "abecd699-bcf4-4298-9cd0-a88bbf1d18c9",
  "status_code": 415,
  "errors": [
    {
      "code": "media_type_error",
      "message": "Content-Type header is wrong",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Status 500

{
  "trace": "abecd699-bcf4-4298-9cd0-a88bbf1d18c9",
  "status_code": 500,
  "errors": [
    {
      "code": "cnfser01",
      "message": "Unexpected internal server error",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Error example

{
  "trace": "abecd699-bcf4-4298-9cd0-a88bbf1d18c9",
  "status_code": 500,
  "errors": [
    {
      "code": "cnfser01",
      "message": "Unexpected internal server error",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Status default

{
  "trace": "abecd699-bcf4-4298-9cd0-a88bbf1d18c9",
  "status_code": 500,
  "errors": [
    {
      "code": "cnfser01",
      "message": "Unexpected internal server error",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Error example

{
  "trace": "abecd699-bcf4-4298-9cd0-a88bbf1d18c9",
  "status_code": 500,
  "errors": [
    {
      "code": "cnfser01",
      "message": "Unexpected internal server error",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

List all Sources

List all Sources.

GET /v1/instances/{instance_id}/sources

(eventNotifications *EventNotificationsV1) ListSources(listSourcesOptions *ListSourcesOptions) (result *SourceList, response *core.DetailedResponse, err error)

(eventNotifications *EventNotificationsV1) ListSourcesWithContext(ctx context.Context, listSourcesOptions *ListSourcesOptions) (result *SourceList, response *core.DetailedResponse, err error)

listSources(params)

list_sources(self,
        instance_id: str,
        *,
        limit: int = None,
        offset: int = None,
        search: str = None,
        **kwargs
    ) -> DetailedResponse

ServiceCall<SourceList> listSources(ListSourcesOptions listSourcesOptions)

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

event-notifications.sources.list

Auditing

Calling this method generates the following auditing event.

event-notifications.sources.list

Request

Instantiate the ListSourcesOptions struct and set the fields to provide parameter values for the ListSources method.

Use the ListSourcesOptions.Builder to create a ListSourcesOptions object that contains the parameter values for the listSources method.

Path Parameters

instance_id
Required*
string
Unique identifier for IBM Cloud Event Notifications instance

Possible values: 10 ≤ length ≤ 256, Value must match regular expression [a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]

Query Parameters

limit
int64
Page limit for paginated results

Possible values: 1 ≤ value ≤ 100
Default: 10
offset
int64
offset for paginated results

Possible values: value ≥ 0
Default: 0
search
string
Search string for filtering results

Possible values: 1 ≤ length ≤ 100, Value must match regular expression [a-zA-Z0-9]

parameter

WithContext method only

ListSourcesOptions

The ListSources options.

parameters

instanceId
Required*
string
Unique identifier for IBM Cloud Event Notifications instance.

Possible values: 10 ≤ length ≤ 256, Value must match regular expression /[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]/
limit
number
Page limit for paginated results.

Possible values: 1 ≤ value ≤ 100
offset
number
offset for paginated results.

Possible values: value ≥ 0
search
string
Search string for filtering results.

Possible values: 1 ≤ length ≤ 100, Value must match regular expression /[a-zA-Z0-9]/

parameters

instance_id
Required*
str
Unique identifier for IBM Cloud Event Notifications instance.

Possible values: 10 ≤ length ≤ 256, Value must match regular expression /[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]/
limit
int
Page limit for paginated results.

Possible values: 1 ≤ value ≤ 100
offset
int
offset for paginated results.

Possible values: value ≥ 0
search
str
Search string for filtering results.

Possible values: 1 ≤ length ≤ 100, Value must match regular expression /[a-zA-Z0-9]/

ListSourcesOptions

The listSources options.

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}" "{base_url}/v1/instances/{instance_id}/sources"

Example request

listSourcesOptions := eventNotificationsService.NewListSourcesOptions(
  instanceID,
)

sourceList, response, err := eventNotificationsService.ListSources(listSourcesOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(sourceList, "", "  ")
fmt.Println(string(b))

Example request

const params = {
  instanceId,
};

let res;
try {
  res = await eventNotificationsService.listSources(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}

Example request

ListSourcesOptions listSourcesOptions = new ListSourcesOptions.Builder()
        .instanceId(instanceId)
        .build();

Response<SourceList> response = eventNotificationsService.listSources(listSourcesOptions).execute();
SourceList sourceList = response.getResult();

System.out.println(sourceList);

Example request

source_list = event_notifications_service.list_sources(
  instance_id
).get_result()

print(json.dumps(source_list, indent=2))

Response

Response Body

SourceList

Payload describing a source list request

SourceList

Payload describing a source list request.

Examples:

View

SourceList

Payload describing a source list request.

Examples:

View

SourceList

Payload describing a source list request.

Examples:

View

SourceList

Payload describing a source list request.

Examples:

View

Status Code

200
Payload describing the Source
401
Trying to access the API with unauthorized token
500
Internal server error
default
Unexpected Error

Example responses

Status 200

{
  "total_count": 2,
  "limit": 10,
  "offset": 0,
  "sources": [
    {
      "enabled": true,
      "description": "This source is related cloud events",
      "id": "00bb34e5-b8c1-4159-af15-8bc6980c3ab2:api",
      "name": "CloudEvents Source",
      "type": "api",
      "topic_count": 0,
      "updated_at": "2021-08-19T05:30:03.696492Z"
    },
    {
      "enabled": true,
      "description": "This source is used to test integration tests",
      "id": "crn:v1:staging:public:compliance:us-south:a/41c340e7fb0b46d9a1a34eaa91fe94d4:2a555506-1d8b-457c-a16b-9d4ad05685ec::",
      "name": "Push Source1",
      "type": "bluemix.public.compliance",
      "topic_count": 1,
      "updated_at": "2021-08-18T19:14:13.916436Z"
    }
  ],
  "first": {
    "href": "https://us-south.event-notifications.cloud.ibm.com/event-notifications/v1/instances/9xxxxx-xxxxx-xxxxx-b3cd-xxxxx/sources?limit=10&offset=0"
  },
  "next": {
    "href": "https://us-south.event-notifications.cloud.ibm.com/event-notifications/v1/instances/9xxxxx-xxxxx-xxxxx-b3cd-xxxxx/sources?limit=10&offset=10"
  }
}

Success example

{
  "total_count": 2,
  "limit": 10,
  "offset": 0,
  "sources": [
    {
      "enabled": true,
      "description": "This source is related cloud events",
      "id": "00bb34e5-b8c1-4159-af15-8bc6980c3ab2:api",
      "name": "CloudEvents Source",
      "type": "api",
      "topic_count": 0,
      "updated_at": "2021-08-19T05:30:03.696492Z"
    },
    {
      "enabled": true,
      "description": "This source is used to test integration tests",
      "id": "crn:v1:staging:public:compliance:us-south:a/41c340e7fb0b46d9a1a34eaa91fe94d4:2a555506-1d8b-457c-a16b-9d4ad05685ec::",
      "name": "Push Source1",
      "type": "bluemix.public.compliance",
      "topic_count": 1,
      "updated_at": "2021-08-18T19:14:13.916436Z"
    }
  ],
  "first": {
    "href": "https://us-south.event-notifications.cloud.ibm.com/event-notifications/v1/instances/9xxxxx-xxxxx-xxxxx-b3cd-xxxxx/sources?limit=10&offset=0"
  },
  "next": {
    "href": "https://us-south.event-notifications.cloud.ibm.com/event-notifications/v1/instances/9xxxxx-xxxxx-xxxxx-b3cd-xxxxx/sources?limit=10&offset=10"
  }
}

Status 401

{
  "trace": "c327fb84-bd47-4726-9946-01f6ecb29734",
  "status_code": 401,
  "errors": [
    {
      "code": "unauthorized",
      "message": "User authorization failed",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-authentication"
    }
  ]
}

Error example

{
  "trace": "c327fb84-bd47-4726-9946-01f6ecb29734",
  "status_code": 401,
  "errors": [
    {
      "code": "unauthorized",
      "message": "User authorization failed",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-authentication"
    }
  ]
}

Status 500

{
  "trace": "abecd699-bcf4-4298-9cd0-a88bbf1d18c9",
  "status_code": 500,
  "errors": [
    {
      "code": "cnfser01",
      "message": "Unexpected internal server error",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Error example

{
  "trace": "abecd699-bcf4-4298-9cd0-a88bbf1d18c9",
  "status_code": 500,
  "errors": [
    {
      "code": "cnfser01",
      "message": "Unexpected internal server error",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Status default

{
  "trace": "abecd699-bcf4-4298-9cd0-a88bbf1d18c9",
  "status_code": 500,
  "errors": [
    {
      "code": "cnfser01",
      "message": "Unexpected internal server error",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Error example

{
  "trace": "abecd699-bcf4-4298-9cd0-a88bbf1d18c9",
  "status_code": 500,
  "errors": [
    {
      "code": "cnfser01",
      "message": "Unexpected internal server error",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Get a Source

Get a Source.

GET /v1/instances/{instance_id}/sources/{id}

(eventNotifications *EventNotificationsV1) GetSource(getSourceOptions *GetSourceOptions) (result *Source, response *core.DetailedResponse, err error)

(eventNotifications *EventNotificationsV1) GetSourceWithContext(ctx context.Context, getSourceOptions *GetSourceOptions) (result *Source, response *core.DetailedResponse, err error)

getSource(params)

get_source(self,
        instance_id: str,
        id: str,
        **kwargs
    ) -> DetailedResponse

ServiceCall<Source> getSource(GetSourceOptions getSourceOptions)

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

event-notifications.sources.read

Auditing

Calling this method generates the following auditing event.

event-notifications.sources.read

Request

Instantiate the GetSourceOptions struct and set the fields to provide parameter values for the GetSource method.

Use the GetSourceOptions.Builder to create a GetSourceOptions object that contains the parameter values for the getSource method.

Path Parameters

instance_id
Required*
string
Unique identifier for IBM Cloud Event Notifications instance

Possible values: 10 ≤ length ≤ 256, Value must match regular expression [a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]
id
Required*
string
Unique identifier for Source

Possible values: 1 ≤ length ≤ 100, Value must match regular expression [a-zA-Z0-9-:_]*

parameter

WithContext method only

GetSourceOptions

The GetSource options.

parameters

instanceId
Required*
string
Unique identifier for IBM Cloud Event Notifications instance.

Possible values: 10 ≤ length ≤ 256, Value must match regular expression /[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]/
id
Required*
string
Unique identifier for Source.

Possible values: 1 ≤ length ≤ 100, Value must match regular expression /[a-zA-Z0-9-:_]*/

parameters

instance_id
Required*
str
Unique identifier for IBM Cloud Event Notifications instance.

Possible values: 10 ≤ length ≤ 256, Value must match regular expression /[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]/
id
Required*
str
Unique identifier for Source.

Possible values: 1 ≤ length ≤ 100, Value must match regular expression /[a-zA-Z0-9-:_]*/

GetSourceOptions

The getSource options.

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   "{base_url}/v1/instances/{instance_id}/sources/{id}"

Example request

getSourceOptions := eventNotificationsService.NewGetSourceOptions(
  instanceID,
  sourceID,
)

source, response, err := eventNotificationsService.GetSource(getSourceOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(source, "", "  ")
fmt.Println(string(b))

Example request

const params = {
  instanceId,
  id: sourceId,
};

let res;
try {
  res = await eventNotificationsService.getSource(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}

Example request

GetSourceOptions getSourceOptions = new GetSourceOptions.Builder()
        .instanceId(instanceId)
        .id(sourceId)
        .build();

Response<Source> response = eventNotificationsService.getSource(getSourceOptions).execute();
Source source = response.getResult();

System.out.println(source);

Example request

source = event_notifications_service.get_source(
  instance_id,
  id=source_id
).get_result()

print(json.dumps(source, indent=2))

Response

Response Body

Source

Payload describing a source generate request

Source

Payload describing a source generate request.

Examples:

View

Source

Payload describing a source generate request.

Examples:

View

Source

Payload describing a source generate request.

Examples:

View

Source

Payload describing a source generate request.

Examples:

View

Status Code

200
Payload getting the Source
401
Trying to access the API with unauthorized token
404
Requested resource not found
500
Internal server error
default
Unexpected Error

Example responses

Status 200

{
  "description": "this source is related cloud events",
  "enabled": false,
  "id": "00bb34e5-b8c1-4159-af15-8bc6980c3ab2:api",
  "name": "CloudEvents Source",
  "topic_count": 1,
  "topic_names": [
    "updated1 apireview topic"
  ],
  "type": "api",
  "updated_at": "2021-09-14T20:43:47.484072Z"
}

Success example

{
  "description": "this source is related cloud events",
  "enabled": false,
  "id": "00bb34e5-b8c1-4159-af15-8bc6980c3ab2:api",
  "name": "CloudEvents Source",
  "topic_count": 1,
  "topic_names": [
    "updated1 apireview topic"
  ],
  "type": "api",
  "updated_at": "2021-09-14T20:43:47.484072Z"
}

Status 401

{
  "trace": "c327fb84-bd47-4726-9946-01f6ecb29734",
  "status_code": 401,
  "errors": [
    {
      "code": "unauthorized",
      "message": "User authorization failed",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-authentication"
    }
  ]
}

Error example

{
  "trace": "c327fb84-bd47-4726-9946-01f6ecb29734",
  "status_code": 401,
  "errors": [
    {
      "code": "unauthorized",
      "message": "User authorization failed",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-authentication"
    }
  ]
}

Status 404

{
  "trace": "208fddf2-dd25-481d-b180-809422a1b5ac",
  "status_code": 404,
  "errors": [
    {
      "code": "not_found",
      "message": "Requested resource not found",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Error example

{
  "trace": "208fddf2-dd25-481d-b180-809422a1b5ac",
  "status_code": 404,
  "errors": [
    {
      "code": "not_found",
      "message": "Requested resource not found",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Status 500

{
  "trace": "abecd699-bcf4-4298-9cd0-a88bbf1d18c9",
  "status_code": 500,
  "errors": [
    {
      "code": "cnfser01",
      "message": "Unexpected internal server error",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Error example

{
  "trace": "abecd699-bcf4-4298-9cd0-a88bbf1d18c9",
  "status_code": 500,
  "errors": [
    {
      "code": "cnfser01",
      "message": "Unexpected internal server error",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Status default

{
  "trace": "abecd699-bcf4-4298-9cd0-a88bbf1d18c9",
  "status_code": 500,
  "errors": [
    {
      "code": "cnfser01",
      "message": "Unexpected internal server error",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Error example

{
  "trace": "abecd699-bcf4-4298-9cd0-a88bbf1d18c9",
  "status_code": 500,
  "errors": [
    {
      "code": "cnfser01",
      "message": "Unexpected internal server error",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Delete a Source

Delete a Source.

DELETE /v1/instances/{instance_id}/sources/{id}

(eventNotifications *EventNotificationsV1) DeleteSource(deleteSourceOptions *DeleteSourceOptions) (response *core.DetailedResponse, err error)

(eventNotifications *EventNotificationsV1) DeleteSourceWithContext(ctx context.Context, deleteSourceOptions *DeleteSourceOptions) (response *core.DetailedResponse, err error)

deleteSource(params)

delete_source(self,
        instance_id: str,
        id: str,
        **kwargs
    ) -> DetailedResponse

ServiceCall<Void> deleteSource(DeleteSourceOptions deleteSourceOptions)

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

event-notifications.sources.delete

Auditing

Calling this method generates the following auditing event.

event-notifications.sources.delete

Request

Instantiate the DeleteSourceOptions struct and set the fields to provide parameter values for the DeleteSource method.

Use the DeleteSourceOptions.Builder to create a DeleteSourceOptions object that contains the parameter values for the deleteSource method.

Path Parameters

instance_id
Required*
string
Unique identifier for IBM Cloud Event Notifications instance

Possible values: 10 ≤ length ≤ 256, Value must match regular expression [a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]
id
Required*
string
Unique identifier for Source

Possible values: 1 ≤ length ≤ 100, Value must match regular expression [a-zA-Z0-9-:_]*

parameter

WithContext method only

DeleteSourceOptions

The DeleteSource options.

parameters

instanceId
Required*
string
Unique identifier for IBM Cloud Event Notifications instance.

Possible values: 10 ≤ length ≤ 256, Value must match regular expression /[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]/
id
Required*
string
Unique identifier for Source.

Possible values: 1 ≤ length ≤ 100, Value must match regular expression /[a-zA-Z0-9-:_]*/

parameters

instance_id
Required*
str
Unique identifier for IBM Cloud Event Notifications instance.

Possible values: 10 ≤ length ≤ 256, Value must match regular expression /[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]/
id
Required*
str
Unique identifier for Source.

Possible values: 1 ≤ length ≤ 100, Value must match regular expression /[a-zA-Z0-9-:_]*/

DeleteSourceOptions

The deleteSource options.

Example request

curl -X DELETE --location --header "Authorization: Bearer {iam_token}"   "{base_url}/v1/instances/{instance_id}/sources/{id}"

Example request

deleteSourceOptions := eventNotificationsService.NewDeleteSourceOptions(
  instanceID,
  sourceID,
)

response, err := eventNotificationsService.DeleteSource(deleteSourceOptions)
if err != nil {
  panic(err)
}
if response.StatusCode != 204 {
  fmt.Printf("\nUnexpected response status code received from DeleteSource(): %d\n", response.StatusCode)
}

Example request

const params = {
  instanceId,
  id: sourceId,
};

try {
  await eventNotificationsService.deleteSource(params);
} catch (err) {
  console.warn(err);
}

Example request

DeleteSourceOptions deleteSourceOptions = new DeleteSourceOptions.Builder()
        .instanceId(instanceId)
        .id(sourceId)
        .build();

Response<Void> response = eventNotificationsService.deleteSource(deleteSourceOptions).execute();

Example request

response = event_notifications_service.delete_source(
  instance_id,
  id=source_id
)

Response

Status Code

204
Deletion successful with no response content
401
Trying to access the API with unauthorized token
404
Requested resource not found
500
Internal server error
default
Unexpected Error

Example responses

Status 401

{
  "trace": "c327fb84-bd47-4726-9946-01f6ecb29734",
  "status_code": 401,
  "errors": [
    {
      "code": "unauthorized",
      "message": "User authorization failed",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-authentication"
    }
  ]
}

Error example

{
  "trace": "c327fb84-bd47-4726-9946-01f6ecb29734",
  "status_code": 401,
  "errors": [
    {
      "code": "unauthorized",
      "message": "User authorization failed",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-authentication"
    }
  ]
}

Status 404

{
  "trace": "208fddf2-dd25-481d-b180-809422a1b5ac",
  "status_code": 404,
  "errors": [
    {
      "code": "not_found",
      "message": "Requested resource not found",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Error example

{
  "trace": "208fddf2-dd25-481d-b180-809422a1b5ac",
  "status_code": 404,
  "errors": [
    {
      "code": "not_found",
      "message": "Requested resource not found",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Status 500

{
  "trace": "abecd699-bcf4-4298-9cd0-a88bbf1d18c9",
  "status_code": 500,
  "errors": [
    {
      "code": "cnfser01",
      "message": "Unexpected internal server error",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Error example

{
  "trace": "abecd699-bcf4-4298-9cd0-a88bbf1d18c9",
  "status_code": 500,
  "errors": [
    {
      "code": "cnfser01",
      "message": "Unexpected internal server error",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Status default

{
  "trace": "abecd699-bcf4-4298-9cd0-a88bbf1d18c9",
  "status_code": 500,
  "errors": [
    {
      "code": "cnfser01",
      "message": "Unexpected internal server error",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Error example

{
  "trace": "abecd699-bcf4-4298-9cd0-a88bbf1d18c9",
  "status_code": 500,
  "errors": [
    {
      "code": "cnfser01",
      "message": "Unexpected internal server error",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Update details of a Source

Update details of a Source.

PATCH /v1/instances/{instance_id}/sources/{id}

(eventNotifications *EventNotificationsV1) UpdateSource(updateSourceOptions *UpdateSourceOptions) (result *Source, response *core.DetailedResponse, err error)

(eventNotifications *EventNotificationsV1) UpdateSourceWithContext(ctx context.Context, updateSourceOptions *UpdateSourceOptions) (result *Source, response *core.DetailedResponse, err error)

updateSource(params)

update_source(self,
        instance_id: str,
        id: str,
        *,
        name: str = None,
        description: str = None,
        enabled: bool = None,
        **kwargs
    ) -> DetailedResponse

ServiceCall<Source> updateSource(UpdateSourceOptions updateSourceOptions)

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

event-notifications.sources.update

Auditing

Calling this method generates the following auditing event.

event-notifications.sources.update

Request

Instantiate the UpdateSourceOptions struct and set the fields to provide parameter values for the UpdateSource method.

Use the UpdateSourceOptions.Builder to create a UpdateSourceOptions object that contains the parameter values for the updateSource method.

Path Parameters

instance_id
Required*
string
Unique identifier for IBM Cloud Event Notifications instance

Possible values: 10 ≤ length ≤ 256, Value must match regular expression [a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]
id
Required*
string
Unique identifier for Source

Possible values: 1 ≤ length ≤ 100, Value must match regular expression [a-zA-Z0-9-:_]*

Request Body

Required*

SourceUpdate

Source update object

Examples:

View

parameter

WithContext method only

UpdateSourceOptions

The UpdateSource options.

parameters

instanceId
Required*
string
Unique identifier for IBM Cloud Event Notifications instance.

Possible values: 10 ≤ length ≤ 256, Value must match regular expression /[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]/
id
Required*
string
Unique identifier for Source.

Possible values: 1 ≤ length ≤ 100, Value must match regular expression /[a-zA-Z0-9-:_]*/
name
string
Name of the source.

Possible values: 1 ≤ length ≤ 255, Value must match regular expression /[a-zA-Z 0-9-_\/.?:'\";,+=!#@$%^&*()]*/
description
string
Description of the source.

Possible values: 1 ≤ length ≤ 255, Value must match regular expression /[a-zA-Z 0-9-_\/.?:'\";,+=!#@$%^&*()]*/
enabled
boolean
Whether the source is enabled or not.

Default: true

parameters

instance_id
Required*
str
Unique identifier for IBM Cloud Event Notifications instance.

Possible values: 10 ≤ length ≤ 256, Value must match regular expression /[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]/
id
Required*
str
Unique identifier for Source.

Possible values: 1 ≤ length ≤ 100, Value must match regular expression /[a-zA-Z0-9-:_]*/
name
str
Name of the source.

Possible values: 1 ≤ length ≤ 255, Value must match regular expression /[a-zA-Z 0-9-_\/.?:'\";,+=!#@$%^&*()]*/
description
str
Description of the source.

Possible values: 1 ≤ length ≤ 255, Value must match regular expression /[a-zA-Z 0-9-_\/.?:'\";,+=!#@$%^&*()]*/
enabled
bool
Whether the source is enabled or not.

Default: true

UpdateSourceOptions

The updateSource options.

Example request

curl -X PATCH --location --header "Authorization: Bearer {iam_token}"   --header "Content-Type: application/json"   --data '{"name":"Event Notification Create Source Acme","description":"This source is used for Acme Bank","enabled":false}'   "{base_url}/v1/instances/{instance_id}/sources/{id}"

Example request

updateSourceOptions := eventNotificationsService.NewUpdateSourceOptions(
  instanceID,
  sourceID,
)
updateSourceOptions.SetName(*core.StringPtr("Event Notification update Source Acme"))
updateSourceOptions.SetDescription(*core.StringPtr("This source is used for updated Acme Bank"))
updateSourceOptions.SetEnabled(true)

source, response, err := eventNotificationsService.UpdateSource(updateSourceOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(source, "", "  ")
fmt.Println(string(b))

Example request

const params = {
  instanceId,
  id: sourceId,
  name: 'Event Notification update Source Acme',
  description: 'This source is used for updated Acme Bank',
  enabled: true,
};

let res;
try {
  res = await eventNotificationsService.updateSource(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}

Example request

UpdateSourceOptions updateSourceOptions = new UpdateSourceOptions.Builder()
        .instanceId(instanceId)
        .id(sourceId)
        .name("Event Notification update Source Acme")
        .description("This source is used for updated Acme Bank")
        .enabled(true)
        .build();

Response<Source> response = eventNotificationsService.updateSource(updateSourceOptions).execute();
Source source = response.getResult();

System.out.println(source);

Example request

source = event_notifications_service.update_source(
  instance_id,
  id=source_id,
  name='Event Notification update Source Acme',
  description='This source is used for updated Acme Bank',
  enabled=True
).get_result()

print(json.dumps(source, indent=2))

Response

Response Body

Source

Payload describing a source generate request

Source

Payload describing a source generate request.

Examples:

View

Source

Payload describing a source generate request.

Examples:

View

Source

Payload describing a source generate request.

Examples:

View

Source

Payload describing a source generate request.

Examples:

View

Status Code

200
Payload getting the Source
400
Bad or incorrect request body
401
Trying to access the API with unauthorized token
404
Requested resource not found
409
Trying to create duplicate source
415
Request body type is not application/json
500
Internal server error
default
Unexpected Error

Example responses

Status 200

{
  "description": "this source is related cloud events",
  "enabled": false,
  "id": "00bb34e5-b8c1-4159-af15-8bc6980c3ab2:api",
  "name": "CloudEvents Source",
  "topic_count": 1,
  "topic_names": [
    "updated1 apireview topic"
  ],
  "type": "api",
  "updated_at": "2021-09-14T20:43:47.484072Z"
}

Success example

{
  "description": "this source is related cloud events",
  "enabled": false,
  "id": "00bb34e5-b8c1-4159-af15-8bc6980c3ab2:api",
  "name": "CloudEvents Source",
  "topic_count": 1,
  "topic_names": [
    "updated1 apireview topic"
  ],
  "type": "api",
  "updated_at": "2021-09-14T20:43:47.484072Z"
}

Status 400

{
  "trace": "11a35929-7cb8-4f06-bd64-abe9c391b06d",
  "status_code": 400,
  "errors": [
    {
      "code": "incorrect_json",
      "message": "Required JSON parameters missing or incorrect",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Error example

{
  "trace": "11a35929-7cb8-4f06-bd64-abe9c391b06d",
  "status_code": 400,
  "errors": [
    {
      "code": "incorrect_json",
      "message": "Required JSON parameters missing or incorrect",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Status 401

{
  "trace": "c327fb84-bd47-4726-9946-01f6ecb29734",
  "status_code": 401,
  "errors": [
    {
      "code": "unauthorized",
      "message": "User authorization failed",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-authentication"
    }
  ]
}

Error example

{
  "trace": "c327fb84-bd47-4726-9946-01f6ecb29734",
  "status_code": 401,
  "errors": [
    {
      "code": "unauthorized",
      "message": "User authorization failed",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-authentication"
    }
  ]
}

Status 404

{
  "trace": "208fddf2-dd25-481d-b180-809422a1b5ac",
  "status_code": 404,
  "errors": [
    {
      "code": "not_found",
      "message": "Requested resource not found",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Error example

{
  "trace": "208fddf2-dd25-481d-b180-809422a1b5ac",
  "status_code": 404,
  "errors": [
    {
      "code": "not_found",
      "message": "Requested resource not found",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Status 409

{
  "trace": "9e948d31-a5be-42be-9dc1-a1006ba9d542",
  "status_code": 409,
  "errors": [
    {
      "code": "source_conflict",
      "message": "Duplicate source name",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Error example

{
  "trace": "9e948d31-a5be-42be-9dc1-a1006ba9d542",
  "status_code": 409,
  "errors": [
    {
      "code": "source_conflict",
      "message": "Duplicate source name",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Status 415

{
  "trace": "abecd699-bcf4-4298-9cd0-a88bbf1d18c9",
  "status_code": 415,
  "errors": [
    {
      "code": "media_type_error",
      "message": "Content-Type header is wrong",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Error example

{
  "trace": "abecd699-bcf4-4298-9cd0-a88bbf1d18c9",
  "status_code": 415,
  "errors": [
    {
      "code": "media_type_error",
      "message": "Content-Type header is wrong",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Status 500

{
  "trace": "abecd699-bcf4-4298-9cd0-a88bbf1d18c9",
  "status_code": 500,
  "errors": [
    {
      "code": "cnfser01",
      "message": "Unexpected internal server error",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Error example

{
  "trace": "abecd699-bcf4-4298-9cd0-a88bbf1d18c9",
  "status_code": 500,
  "errors": [
    {
      "code": "cnfser01",
      "message": "Unexpected internal server error",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Status default

{
  "trace": "abecd699-bcf4-4298-9cd0-a88bbf1d18c9",
  "status_code": 500,
  "errors": [
    {
      "code": "cnfser01",
      "message": "Unexpected internal server error",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Error example

{
  "trace": "abecd699-bcf4-4298-9cd0-a88bbf1d18c9",
  "status_code": 500,
  "errors": [
    {
      "code": "cnfser01",
      "message": "Unexpected internal server error",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Create a new Topic

Create a new Topic.

POST /v1/instances/{instance_id}/topics

(eventNotifications *EventNotificationsV1) CreateTopic(createTopicOptions *CreateTopicOptions) (result *TopicResponse, response *core.DetailedResponse, err error)

(eventNotifications *EventNotificationsV1) CreateTopicWithContext(ctx context.Context, createTopicOptions *CreateTopicOptions) (result *TopicResponse, response *core.DetailedResponse, err error)

createTopic(params)

create_topic(self,
        instance_id: str,
        name: str,
        *,
        description: str = None,
        sources: List['SourcesItems'] = None,
        **kwargs
    ) -> DetailedResponse

ServiceCall<TopicResponse> createTopic(CreateTopicOptions createTopicOptions)

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

event-notifications.topics.create

Auditing

Calling this method generates the following auditing event.

event-notifications.topics.create

Request

Instantiate the CreateTopicOptions struct and set the fields to provide parameter values for the CreateTopic method.

Use the CreateTopicOptions.Builder to create a CreateTopicOptions object that contains the parameter values for the createTopic method.

Path Parameters

instance_id
Required*
string
Unique identifier for IBM Cloud Event Notifications instance

Possible values: 10 ≤ length ≤ 256, Value must match regular expression [a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]

Request Body

Required*

TopicCreate

Topic object

Examples:

View

parameter

WithContext method only

CreateTopicOptions

The CreateTopic options.

parameters

instanceId
Required*
string
Unique identifier for IBM Cloud Event Notifications instance.

Possible values: 10 ≤ length ≤ 256, Value must match regular expression /[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]/
name
Required*
string
Name of the topic.

Possible values: 1 ≤ length ≤ 255, Value must match regular expression /[a-zA-Z 0-9-_\/.?:'\";,+=!#@$%^&*()]*/
description
string
Description of the topic.

Possible values: 1 ≤ length ≤ 255, Value must match regular expression /[a-zA-Z 0-9-_\/.?:'\";,+=!#@$%^&*()]*/
sources
List of sources.

Possible values: 0 ≤ number of items ≤ 100
Examples:
value
_source
_lines
_html

parameters

instance_id
Required*
str
Unique identifier for IBM Cloud Event Notifications instance.

Possible values: 10 ≤ length ≤ 256, Value must match regular expression /[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]/
name
Required*
str
Name of the topic.

Possible values: 1 ≤ length ≤ 255, Value must match regular expression /[a-zA-Z 0-9-_\/.?:'\";,+=!#@$%^&*()]*/
description
str
Description of the topic.

Possible values: 1 ≤ length ≤ 255, Value must match regular expression /[a-zA-Z 0-9-_\/.?:'\";,+=!#@$%^&*()]*/
sources
List of sources.

Possible values: 0 ≤ number of items ≤ 100
Examples:
value
_source
_lines
_html

CreateTopicOptions

The createTopic options.

Example request

curl -X POST --location --header "Authorization: Bearer {iam_token}"   --header "Content-Type: application/json"   --data '{"name":"Event Notification Update Admin ashwin kul","description":"This topic is used for EN spoof tests","sources":[{"id":"96dbf538-9fa7-4745-b9e4-32bb6f1dc47a:api","rules":[{"enabled":true,"event_type_filter":"$.notification_event_info.event_type == 'test'","notification_filter":"$.notification.findings[0].severity == 'LOW'"},{"enabled":false,"event_type_filter":"$.notification_event_info.event_type == 'test'","notification_filter":"$.notification.findings[0].severity == 'HIGH'"},{"enabled":true,"event_type_filter":"$.notification_event_info.event_type == 'cert_manager'"}]}]}'   "{base_url}/v1/instances/{instance_id}/topics"

Example request

rulesModel := &eventnotificationsv1.Rules{
  Enabled:            core.BoolPtr(false),
  EventTypeFilter:    core.StringPtr("$.notification_event_info.event_type == 'cert_manager'"),
  NotificationFilter: core.StringPtr("$.notification.findings[0].severity == 'MODERATE'"),
}

topicUpdateSourcesItemModel := &eventnotificationsv1.SourcesItems{
  ID:    core.StringPtr(sourceID),
  Rules: []eventnotificationsv1.Rules{*rulesModel},
}

createTopicOptions := &eventnotificationsv1.CreateTopicOptions{
  InstanceID:  core.StringPtr(instanceID),
  Name:        core.StringPtr(topicName),
  Description: core.StringPtr("This topic is used for routing all compliance related notifications to the appropriate destinations"),
  Sources:     []eventnotificationsv1.SourcesItems{*topicUpdateSourcesItemModel},
}

topicResponse, response, err := eventNotificationsService.CreateTopic(createTopicOptions)
if err != nil {
  panic(err)
}
topicID = string(*topicResponse.ID)

b, _ := json.MarshalIndent(topicResponse, "", "  ")
fmt.Println(string(b))

Example request

// Rules
const rulesModel = {
  enabled: false,
  event_type_filter: "$.notification_event_info.event_type == 'cert_manager'",
  notification_filter: "$.notification.findings[0].severity == 'MODERATE'",
};

// TopicUpdateSourcesItem
const topicUpdateSourcesItemModel = {
  id: sourceId,
  rules: [rulesModel],
};

const params = {
  instanceId,
  name: topicName,
  description:
    'This topic is used for routing all compliance related notifications to the appropriate destinations',
  sources: [topicUpdateSourcesItemModel],
};

let res;
try {
  res = await eventNotificationsService.createTopic(params);
  console.log(JSON.stringify(res.result, null, 2));
  topicId = res.result.id;
} catch (err) {
  console.warn(err);
}

Example request

Rules rulesModel = new Rules.Builder()
        .enabled(true)
        .eventTypeFilter("$.notification_event_info.event_type == 'cert_manager'")
        .notificationFilter("$.notification.findings[0].severity == 'MODERATE'")
        .build();

SourcesItems topicUpdateSourcesItemModel = new SourcesItems.Builder()
        .id(sourceId)
        .rules(new java.util.ArrayList<Rules>(java.util.Arrays.asList(rulesModel)))
        .build();


CreateTopicOptions createTopicOptions = new CreateTopicOptions.Builder()
        .instanceId(instanceId)
        .name(topicName)
        .description("This topic is used for routing all compliance related notifications to the appropriate destinations")
        .sources(new java.util.ArrayList<SourcesItems>(java.util.Arrays.asList(topicUpdateSourcesItemModel)))
        .build();

Response<TopicResponse> response = eventNotificationsService.createTopic(createTopicOptions).execute();
TopicResponse topicResponse = response.getResult();

System.out.println(topicResponse);

Example request

rules_model = {
  'enabled': False,
  'event_type_filter': '$.notification_event_info.event_type == \'cert_manager\'',
  'notification_filter': '$.notification.findings[0].severity == \'MODERATE\'',
}

# Construct a dict representation of a TopicUpdateSourcesItem model
topic_update_sources_item_model = {
  'id': source_id,
  'rules': [rules_model],
}

topic = event_notifications_service.create_topic(
  instance_id,
  name=topic_name,
  description='This topic is used for routing all compliance related notifications to the appropriate destinations',
  sources=[topic_update_sources_item_model]
).get_result()

print(json.dumps(topic, indent=2))

Response

Response Body

TopicResponse

Topic object

TopicResponse

Topic object.

Examples:

View

TopicResponse

Topic object.

Examples:

View

TopicResponse

Topic object.

Examples:

View

TopicResponse

Topic object.

Examples:

View

Status Code

201
Response body after topic creation
400
Bad or incorrect request body
401
Trying to access the API with unauthorized token
404
Requested resource not found
409
Trying to create duplicate topic
415
Request body type is not application/json
500
Internal server error
default
Unexpected Error

Example responses

Status 201

{
  "created_at": "2021-10-07T06:51:37.707653235Z",
  "description": "This topic is used for EN e2e tests",
  "id": "81207685-7037-4d3a-b022-b7b974f6395b",
  "name": "EN Topic"
}

Success example

{
  "created_at": "2021-10-07T06:51:37.707653235Z",
  "description": "This topic is used for EN e2e tests",
  "id": "81207685-7037-4d3a-b022-b7b974f6395b",
  "name": "EN Topic"
}

Status 400

{
  "trace": "11a35929-7cb8-4f06-bd64-abe9c391b06d",
  "status_code": 400,
  "errors": [
    {
      "code": "incorrect_json",
      "message": "Required JSON parameters missing or incorrect",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Error example

{
  "trace": "11a35929-7cb8-4f06-bd64-abe9c391b06d",
  "status_code": 400,
  "errors": [
    {
      "code": "incorrect_json",
      "message": "Required JSON parameters missing or incorrect",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Status 401

{
  "trace": "c327fb84-bd47-4726-9946-01f6ecb29734",
  "status_code": 401,
  "errors": [
    {
      "code": "unauthorized",
      "message": "User authorization failed",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-authentication"
    }
  ]
}

Error example

{
  "trace": "c327fb84-bd47-4726-9946-01f6ecb29734",
  "status_code": 401,
  "errors": [
    {
      "code": "unauthorized",
      "message": "User authorization failed",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-authentication"
    }
  ]
}

Status 404

{
  "trace": "208fddf2-dd25-481d-b180-809422a1b5ac",
  "status_code": 404,
  "errors": [
    {
      "code": "not_found",
      "message": "Requested resource not found",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Error example

{
  "trace": "208fddf2-dd25-481d-b180-809422a1b5ac",
  "status_code": 404,
  "errors": [
    {
      "code": "not_found",
      "message": "Requested resource not found",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Status 409

{
  "trace": "9e948d31-a5be-42be-9dc1-a1006ba9d542",
  "status_code": 409,
  "errors": [
    {
      "code": "topic_conflict",
      "message": "Duplicate topic name",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Error example

{
  "trace": "9e948d31-a5be-42be-9dc1-a1006ba9d542",
  "status_code": 409,
  "errors": [
    {
      "code": "topic_conflict",
      "message": "Duplicate topic name",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Status 415

{
  "trace": "abecd699-bcf4-4298-9cd0-a88bbf1d18c9",
  "status_code": 415,
  "errors": [
    {
      "code": "media_type_error",
      "message": "Content-Type header is wrong",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Error example

{
  "trace": "abecd699-bcf4-4298-9cd0-a88bbf1d18c9",
  "status_code": 415,
  "errors": [
    {
      "code": "media_type_error",
      "message": "Content-Type header is wrong",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Status 500

{
  "trace": "abecd699-bcf4-4298-9cd0-a88bbf1d18c9",
  "status_code": 500,
  "errors": [
    {
      "code": "cnfser01",
      "message": "Unexpected internal server error",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Error example

{
  "trace": "abecd699-bcf4-4298-9cd0-a88bbf1d18c9",
  "status_code": 500,
  "errors": [
    {
      "code": "cnfser01",
      "message": "Unexpected internal server error",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Status default

{
  "trace": "abecd699-bcf4-4298-9cd0-a88bbf1d18c9",
  "status_code": 500,
  "errors": [
    {
      "code": "cnfser01",
      "message": "Unexpected internal server error",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Error example

{
  "trace": "abecd699-bcf4-4298-9cd0-a88bbf1d18c9",
  "status_code": 500,
  "errors": [
    {
      "code": "cnfser01",
      "message": "Unexpected internal server error",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

List all Topics

List all Topics.

GET /v1/instances/{instance_id}/topics

(eventNotifications *EventNotificationsV1) ListTopics(listTopicsOptions *ListTopicsOptions) (result *TopicList, response *core.DetailedResponse, err error)

(eventNotifications *EventNotificationsV1) ListTopicsWithContext(ctx context.Context, listTopicsOptions *ListTopicsOptions) (result *TopicList, response *core.DetailedResponse, err error)

listTopics(params)

list_topics(self,
        instance_id: str,
        *,
        limit: int = None,
        offset: int = None,
        search: str = None,
        **kwargs
    ) -> DetailedResponse

ServiceCall<TopicList> listTopics(ListTopicsOptions listTopicsOptions)

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

event-notifications.topics.list

Auditing

Calling this method generates the following auditing event.

event-notifications.topics.list

Request

Instantiate the ListTopicsOptions struct and set the fields to provide parameter values for the ListTopics method.

Use the ListTopicsOptions.Builder to create a ListTopicsOptions object that contains the parameter values for the listTopics method.

Path Parameters

instance_id
Required*
string
Unique identifier for IBM Cloud Event Notifications instance

Possible values: 10 ≤ length ≤ 256, Value must match regular expression [a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]

Query Parameters

limit
int64
Page limit for paginated results

Possible values: 1 ≤ value ≤ 100
Default: 10
offset
int64
offset for paginated results

Possible values: value ≥ 0
Default: 0
search
string
Search string for filtering results

Possible values: 1 ≤ length ≤ 100, Value must match regular expression [a-zA-Z0-9]

parameter

WithContext method only

ListTopicsOptions

The ListTopics options.

parameters

instanceId
Required*
string
Unique identifier for IBM Cloud Event Notifications instance.

Possible values: 10 ≤ length ≤ 256, Value must match regular expression /[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]/
limit
number
Page limit for paginated results.

Possible values: 1 ≤ value ≤ 100
offset
number
offset for paginated results.

Possible values: value ≥ 0
search
string
Search string for filtering results.

Possible values: 1 ≤ length ≤ 100, Value must match regular expression /[a-zA-Z0-9]/

parameters

instance_id
Required*
str
Unique identifier for IBM Cloud Event Notifications instance.

Possible values: 10 ≤ length ≤ 256, Value must match regular expression /[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]/
limit
int
Page limit for paginated results.

Possible values: 1 ≤ value ≤ 100
offset
int
offset for paginated results.

Possible values: value ≥ 0
search
str
Search string for filtering results.

Possible values: 1 ≤ length ≤ 100, Value must match regular expression /[a-zA-Z0-9]/

ListTopicsOptions

The listTopics options.

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}" "{base_url}/v1/instances/{instance_id}/topics"

Example request

listTopicsOptions := eventNotificationsService.NewListTopicsOptions(
  instanceID,
)

topicList, response, err := eventNotificationsService.ListTopics(listTopicsOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(topicList, "", "  ")
fmt.Println(string(b))

Example request

const params = {
  instanceId,
};

let res;
try {
  res = await eventNotificationsService.listTopics(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}

Example request

ListTopicsOptions listTopicsOptions = new ListTopicsOptions.Builder()
        .instanceId(instanceId)
        .build();

Response<TopicList> response = eventNotificationsService.listTopics(listTopicsOptions).execute();
TopicList topicList = response.getResult();

System.out.println(topicList);

Example request

topic_list = event_notifications_service.list_topics(
  instance_id
).get_result()

print(json.dumps(topic_list, indent=2))

Response

Response Body

TopicList

Topic list object

TopicList

Topic list object.

Examples:

View

TopicList

Topic list object.

Examples:

View

TopicList

Topic list object.

Examples:

View

TopicList

Topic list object.

Examples:

View

Status Code

200
Payload describing the Topic
401
Trying to access the API with unauthorized token
500
Internal server error
default
Unexpected Error

Example responses

Status 200

{
  "total_count": 2,
  "offset": 0,
  "limit": 10,
  "topics": [
    {
      "source_count": 2,
      "sources_names": [
        "Push Source",
        "Custom source"
      ],
      "subscription_count": 3,
      "description": "To send events to all EN developers",
      "id": "33d2b8d5-8ab8-46c7-97b9-c508afbf0701",
      "name": "Developers topic"
    },
    {
      "source_count": 1,
      "sources_names": [
        "Push Source1"
      ],
      "subscription_count": 3,
      "description": "This topic is used for EN integration tests",
      "id": "7b23362d-6d48-47ef-847a-c8b291220306",
      "name": "Event Notification Admin encryption1"
    }
  ],
  "first": {
    "href": "https://us-south.event-notifications.cloud.ibm.com/event-notifications/v1/instances/9xxxxx-xxxxx-xxxxx-b3cd-xxxxx/topics?limit=10&offset=0"
  },
  "next": {
    "href": "https://us-south.event-notifications.cloud.ibm.com/event-notifications/v1/instances/9xxxxx-xxxxx-xxxxx-b3cd-xxxxx/topics?limit=10&offset=10"
  }
}

Success example

{
  "total_count": 2,
  "offset": 0,
  "limit": 10,
  "topics": [
    {
      "source_count": 2,
      "sources_names": [
        "Push Source",
        "Custom source"
      ],
      "subscription_count": 3,
      "description": "To send events to all EN developers",
      "id": "33d2b8d5-8ab8-46c7-97b9-c508afbf0701",
      "name": "Developers topic"
    },
    {
      "source_count": 1,
      "sources_names": [
        "Push Source1"
      ],
      "subscription_count": 3,
      "description": "This topic is used for EN integration tests",
      "id": "7b23362d-6d48-47ef-847a-c8b291220306",
      "name": "Event Notification Admin encryption1"
    }
  ],
  "first": {
    "href": "https://us-south.event-notifications.cloud.ibm.com/event-notifications/v1/instances/9xxxxx-xxxxx-xxxxx-b3cd-xxxxx/topics?limit=10&offset=0"
  },
  "next": {
    "href": "https://us-south.event-notifications.cloud.ibm.com/event-notifications/v1/instances/9xxxxx-xxxxx-xxxxx-b3cd-xxxxx/topics?limit=10&offset=10"
  }
}

Status 401

{
  "trace": "c327fb84-bd47-4726-9946-01f6ecb29734",
  "status_code": 401,
  "errors": [
    {
      "code": "unauthorized",
      "message": "User authorization failed",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-authentication"
    }
  ]
}

Error example

{
  "trace": "c327fb84-bd47-4726-9946-01f6ecb29734",
  "status_code": 401,
  "errors": [
    {
      "code": "unauthorized",
      "message": "User authorization failed",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-authentication"
    }
  ]
}

Status 500

{
  "trace": "abecd699-bcf4-4298-9cd0-a88bbf1d18c9",
  "status_code": 500,
  "errors": [
    {
      "code": "cnfser01",
      "message": "Unexpected internal server error",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Error example

{
  "trace": "abecd699-bcf4-4298-9cd0-a88bbf1d18c9",
  "status_code": 500,
  "errors": [
    {
      "code": "cnfser01",
      "message": "Unexpected internal server error",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Status default

{
  "trace": "abecd699-bcf4-4298-9cd0-a88bbf1d18c9",
  "status_code": 500,
  "errors": [
    {
      "code": "cnfser01",
      "message": "Unexpected internal server error",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Error example

{
  "trace": "abecd699-bcf4-4298-9cd0-a88bbf1d18c9",
  "status_code": 500,
  "errors": [
    {
      "code": "cnfser01",
      "message": "Unexpected internal server error",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Get details of a Topic

Get details of a Topic.

GET /v1/instances/{instance_id}/topics/{id}

(eventNotifications *EventNotificationsV1) GetTopic(getTopicOptions *GetTopicOptions) (result *Topic, response *core.DetailedResponse, err error)

(eventNotifications *EventNotificationsV1) GetTopicWithContext(ctx context.Context, getTopicOptions *GetTopicOptions) (result *Topic, response *core.DetailedResponse, err error)

getTopic(params)

get_topic(self,
        instance_id: str,
        id: str,
        *,
        include: str = None,
        **kwargs
    ) -> DetailedResponse

ServiceCall<Topic> getTopic(GetTopicOptions getTopicOptions)

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

event-notifications.topics.read

Auditing

Calling this method generates the following auditing event.

event-notifications.topics.read

Request

Instantiate the GetTopicOptions struct and set the fields to provide parameter values for the GetTopic method.

Use the GetTopicOptions.Builder to create a GetTopicOptions object that contains the parameter values for the getTopic method.

Path Parameters

instance_id
Required*
string
Unique identifier for IBM Cloud Event Notifications instance

Possible values: 10 ≤ length ≤ 256, Value must match regular expression [a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]
id
Required*
string
Unique identifier for Topic

Possible values: length = 36, Value must match regular expression [a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}

Query Parameters

include
string
Include sub topics

Possible values: 1 ≤ length ≤ 20, Value must match regular expression [a-z]

parameter

WithContext method only

GetTopicOptions

The GetTopic options.

parameters

instanceId
Required*
string
Unique identifier for IBM Cloud Event Notifications instance.

Possible values: 10 ≤ length ≤ 256, Value must match regular expression /[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]/
id
Required*
string
Unique identifier for Topic.

Possible values: length = 36, Value must match regular expression /[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}/
include
string
Include sub topics.

Possible values: 1 ≤ length ≤ 20, Value must match regular expression /[a-z]/

parameters

instance_id
Required*
str
Unique identifier for IBM Cloud Event Notifications instance.

Possible values: 10 ≤ length ≤ 256, Value must match regular expression /[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]/
id
Required*
str
Unique identifier for Topic.

Possible values: length = 36, Value must match regular expression /[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}/
include
str
Include sub topics.

Possible values: 1 ≤ length ≤ 20, Value must match regular expression /[a-z]/

GetTopicOptions

The getTopic options.

Example request

curl -X GET --location --header "Authorization: Bearer {iam_token}"   "{base_url}/v1/instances/{instance_id}/topics/{id}"

Example request

getTopicOptions := eventNotificationsService.NewGetTopicOptions(
  instanceID,
  topicID,
)

topic, response, err := eventNotificationsService.GetTopic(getTopicOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(topic, "", "  ")
fmt.Println(string(b))

Example request

const params = {
  instanceId,
  id: topicId,
};

let res;
try {
  res = await eventNotificationsService.getTopic(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}

Example request

GetTopicOptions getTopicOptions = new GetTopicOptions.Builder()
        .instanceId(instanceId)
        .id(topicId)
        .build();

Response<Topic> response = eventNotificationsService.getTopic(getTopicOptions).execute();
Topic topic = response.getResult();

System.out.println(topic);

Example request

topic = event_notifications_service.get_topic(
  instance_id,
  id=topic_id
).get_result()

print(json.dumps(topic, indent=2))

Response

Response Body

Topic

Topic object

Topic

Topic object.

Examples:

View

Topic

Topic object.

Examples:

View

Topic

Topic object.

Examples:

View

Topic

Topic object.

Examples:

View

Status Code

200
Payload describing the Topic
401
Trying to access the API with unauthorized token
404
Requested resource not found
500
Internal server error
default
Unexpected Error

Example responses

Status 200

{
  "description": "This topic is used for routing all compliance related notifications to the appropriate destinations",
  "id": "33d2b8d5-8ab8-46c7-97b9-c508afbf0701",
  "name": "Admin Topic Compliance",
  "source_count": 1,
  "sources": [
    {
      "id": "96dbf538-9fa7-4745-b9e4-32bb6f1dc47a:api",
      "name": "Compliance source",
      "rules": [
        {
          "enabled": true,
          "id": "218f4e30-9af2-4f70-b38b-738f923b0c4b",
          "event_type_filter": "$.notification_event_info.event_type == 'test'",
          "notification_filter": "$.notification.findings[0].severity == 'LOW'",
          "updated_at": "2021-09-08T13:25:20.523533Z"
        },
        {
          "enabled": false,
          "id": "6a061e40-cf93-47b5-809b-59f11e9a4433",
          "event_type_filter": "$.notification_event_info.event_type == 'test'",
          "notification_filter": "$.notification.findings[0].severity == 'HIGH'",
          "updated_at": "2021-09-08T13:25:20.523533Z"
        },
        {
          "enabled": true,
          "id": "6a061e40-cf93-47b5-809b-59f11e9a4433",
          "event_type_filter": "$.notification_event_info.event_type == 'cert_manager'",
          "notification_filter": "$.notification.findings[0].severity == 'MODERATE'",
          "updated_at": "2021-09-08T13:25:20.523533Z"
        }
      ]
    }
  ],
  "subscription_count": 1,
  "subscriptions": [
    {
      "description": "This subscription is to send events from SCC to EN Admins via sms",
      "destination_id": "ec28efee-2236-4c2d-8839-d34f697cfc69",
      "destination_type": "sms_ibm",
      "id": "87bef75e-f826-4aa9-b64d-91af9be5e12b",
      "name": "SMS Subscription on new change",
      "topic_id": "7b23362d-6d48-47ef-847a-c8b291220306",
      "updated_at": "2021-08-20T10:08:46.060316Z"
    }
  ],
  "updated_at": "2021-09-08T13:25:20.475437Z"
}

Success example

{
  "description": "This topic is used for routing all compliance related notifications to the appropriate destinations",
  "id": "33d2b8d5-8ab8-46c7-97b9-c508afbf0701",
  "name": "Admin Topic Compliance",
  "source_count": 1,
  "sources": [
    {
      "id": "96dbf538-9fa7-4745-b9e4-32bb6f1dc47a:api",
      "name": "Compliance source",
      "rules": [
        {
          "enabled": true,
          "id": "218f4e30-9af2-4f70-b38b-738f923b0c4b",
          "event_type_filter": "$.notification_event_info.event_type == 'test'",
          "notification_filter": "$.notification.findings[0].severity == 'LOW'",
          "updated_at": "2021-09-08T13:25:20.523533Z"
        },
        {
          "enabled": false,
          "id": "6a061e40-cf93-47b5-809b-59f11e9a4433",
          "event_type_filter": "$.notification_event_info.event_type == 'test'",
          "notification_filter": "$.notification.findings[0].severity == 'HIGH'",
          "updated_at": "2021-09-08T13:25:20.523533Z"
        },
        {
          "enabled": true,
          "id": "6a061e40-cf93-47b5-809b-59f11e9a4433",
          "event_type_filter": "$.notification_event_info.event_type == 'cert_manager'",
          "notification_filter": "$.notification.findings[0].severity == 'MODERATE'",
          "updated_at": "2021-09-08T13:25:20.523533Z"
        }
      ]
    }
  ],
  "subscription_count": 1,
  "subscriptions": [
    {
      "description": "This subscription is to send events from SCC to EN Admins via sms",
      "destination_id": "ec28efee-2236-4c2d-8839-d34f697cfc69",
      "destination_type": "sms_ibm",
      "id": "87bef75e-f826-4aa9-b64d-91af9be5e12b",
      "name": "SMS Subscription on new change",
      "topic_id": "7b23362d-6d48-47ef-847a-c8b291220306",
      "updated_at": "2021-08-20T10:08:46.060316Z"
    }
  ],
  "updated_at": "2021-09-08T13:25:20.475437Z"
}

Status 401

{
  "trace": "c327fb84-bd47-4726-9946-01f6ecb29734",
  "status_code": 401,
  "errors": [
    {
      "code": "unauthorized",
      "message": "User authorization failed",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-authentication"
    }
  ]
}

Error example

{
  "trace": "c327fb84-bd47-4726-9946-01f6ecb29734",
  "status_code": 401,
  "errors": [
    {
      "code": "unauthorized",
      "message": "User authorization failed",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-authentication"
    }
  ]
}

Status 404

{
  "trace": "208fddf2-dd25-481d-b180-809422a1b5ac",
  "status_code": 404,
  "errors": [
    {
      "code": "not_found",
      "message": "Requested resource not found",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Error example

{
  "trace": "208fddf2-dd25-481d-b180-809422a1b5ac",
  "status_code": 404,
  "errors": [
    {
      "code": "not_found",
      "message": "Requested resource not found",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Status 500

{
  "trace": "abecd699-bcf4-4298-9cd0-a88bbf1d18c9",
  "status_code": 500,
  "errors": [
    {
      "code": "cnfser01",
      "message": "Unexpected internal server error",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Error example

{
  "trace": "abecd699-bcf4-4298-9cd0-a88bbf1d18c9",
  "status_code": 500,
  "errors": [
    {
      "code": "cnfser01",
      "message": "Unexpected internal server error",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Status default

{
  "trace": "abecd699-bcf4-4298-9cd0-a88bbf1d18c9",
  "status_code": 500,
  "errors": [
    {
      "code": "cnfser01",
      "message": "Unexpected internal server error",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Error example

{
  "trace": "abecd699-bcf4-4298-9cd0-a88bbf1d18c9",
  "status_code": 500,
  "errors": [
    {
      "code": "cnfser01",
      "message": "Unexpected internal server error",
      "more_info": "https://cloud.ibm.com/apidocs/event-notifications#event-notifications-api-http-response-codes"
    }
  ]
}

Update details of a Topic

Update details of a Topic.

PUT /v1/instances/{instance_id}/topics/{id}

(eventNotifications *EventNotificationsV1) ReplaceTopic(replaceTopicOptions *ReplaceTopicOptions) (result *Topic, response *core.DetailedResponse, err error)

(eventNotifications *EventNotificationsV1) ReplaceTopicWithContext(ctx context.Context, replaceTopicOptions *ReplaceTopicOptions) (result *Topic, response *core.DetailedResponse, err error)

replaceTopic(params)

replace_topic(self,
        instance_id: str,
        id: str,
        *,
        name: str = None,
        description: str = None,
        sources: List['SourcesItems'] = None,
        **kwargs
    ) -> DetailedResponse

ServiceCall<Topic> replaceTopic(ReplaceTopicOptions replaceTopicOptions)

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

event-notifications.topics.update

Auditing

Calling this method generates the following auditing event.

event-notifications.topics.update

Request

Instantiate the ReplaceTopicOptions struct and set the fields to provide parameter values for the ReplaceTopic method.

Use the ReplaceTopicOptions.Builder to create a ReplaceTopicOptions object that contains the parameter values for the replaceTopic method.

Path Parameters

instance_id
Required*
string
Unique identifier for IBM Cloud Event Notifications instance

Possible values: 10 ≤ length ≤ 256, Value must match regular expression [a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]
id
Required*
string
Unique identifier for Topic

Possible values: length = 36, Value must match regular expression [a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}

Request Body

Required*

TopicUpdate

Topic update object

Examples:

View

parameter

WithContext method only

ReplaceTopicOptions

The ReplaceTopic options.

parameters

instanceId
Required*
string
Unique identifier for IBM Cloud Event Notifications instance.

Possible values: 10 ≤ length ≤ 256, Value must match regular expression /[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]/
id
Required*
string
Unique identifier for Topic.

Possible values: length = 36, Value must match regular expression /[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}/
name
string
Name of the topic.

Possible values: 1 ≤ length ≤ 255, Value must match regular expression /[a-zA-Z 0-9-_\/.?:'\";,+=!#@$%^&*()]*/
description
string
Description of the topic.

Possible values: 1 ≤ length ≤ 255, Value must match regular expression /[a-zA-Z 0-9-_\/.?:'\";,+=!#@$%^&*()]*/
sources
List of sources.

Possible values: 0 ≤ number of items ≤ 100
Examples:
value
_source
_lines
_html

parameters

instance_id
Required*
str
Unique identifier for IBM Cloud Event Notifications instance.

Possible values: 10 ≤ length ≤ 256, Value must match regular expression /[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]/
id
Required*
str
Unique identifier for Topic.

Possible values: length = 36, Value must match regular expression /[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}/

Introduction

SDKs

Endpoint list

Authentication

Error handling

Auditing

Methods

Send a notification

Authorization

Auditing

Request

Path Parameters

instance_id

Request Body

specversion

id

source

type

ibmensourceid

ibmendefaultshort

ibmendefaultlong

time

ibmenseverity

subject

data

any property

datacontenttype

ibmenpushto

ibmenfcmbody

ibmenapnsbody

ibmenapnsheaders

ibmenchromebody

ibmenchromeheaders

ibmenfirefoxbody

ibmenfirefoxheaders

ibmensafaribody

other property

parameter

ctx

SendNotificationsOptions

InstanceID

Body

Specversion

Time

ID

Source

Type

Ibmenseverity

Ibmensourceid

Ibmendefaultshort

Ibmendefaultlong

Subject

Data

Datacontenttype

Ibmenpushto

Ibmenfcmbody

Ibmenapnsbody

Ibmenapnsheaders

Ibmenchromebody

Ibmenchromeheaders

Ibmenfirefoxbody

Ibmenfirefoxheaders

Ibmensafaribody

other property

parameters

instanceId

body

specversion

time

id

source

type

ibmenseverity

ibmensourceid

ibmendefaultshort

ibmendefaultlong

subject

data

datacontenttype

ibmenpushto