Enabling event notifications for projects

As an administrator of projects, you might want to send notifications of events in projects to other users, or human destinations, by using email, SMS, or other supported delivery channels. You might want to send these notifications of events to other applications to build logic by using event-driven programming by using webhooks, for example. This is made possible by the integration between projects and IBM Cloud® Event Notifications.

To send information to Event Notifications, you must connect your projects instance to Event Notifications. For more information about working with Event Notifications, see Getting started with Event Notifications.

How events are collected and sent by projects

When an event of interest takes place in your project instance, projects communicate with a connected Event Notifications instance to forward a notification to a supported destination. Events are generated based on actions that users take within the project. For example, if the validation of a configuration is successful, an event is generated to notify users of this action.

Events for projects

The following table lists the projects events.

Table 1. Actions that generate event notifications in projects
Event type	Description
`check.pipeline.failed`	Changes failed validation. An event is generated when a validation fails.
`config.install-job.failed`	Changes failed to deploy. An event is generated when an architecture deployment fails.
`config.uninstall-job.failed`	Destroy resources failed. An event is generated when the action to destroy configuration resources fails.
`check.pipeline.ready`	Changes require approval. An event is generated when the latest changes require approval.
`config.version.available`	A version update is available. An event is generated when a new version of a deployable architecture is available.
`config.defn.updated`	Changes are ready to deploy. An event is generated when a configuration is updated in the project.
`config.install-job.succeeded`	Deployment complete. An event is generated when a configuration is successfully deployed.
`config.uninstall-job.succeeded`	Destroy resources complete. An event is generated when deployed resources are successfully destroyed.

Enabling notifications

Events that are generated by an instance of the IBM Cloud Projects service can be forwarded to an Event Notifications service instance that is available in the same account.

Connecting to Event Notifications in the console

Before you can enable notifications for projects, be sure that you have an Event Notifications service instance that is in the same account as your projects instance. Then, you can connect to the Event Notifications service from Manage > Notifications in your project.

In the console, click the Navigation Menu icon > Projects.
Select the project that you'd like to connect to Event Notifications.
Click Manage > Notifications.
In the Connected instance section, click Connect.
Add a name to the connection and optionally provide a description.
Select the resource group and Event Notifications service instance that you want to connect.

If an IAM authorization between projects and Event Notifications doesn't exist in your account, a dialog is displayed. Follow the prompts to grant access between the services.
1. To grant access between projects and Event Notifications, click Authorize.
2. Select Event Notifications as the target service.
3. From the list of instances, select the Event Notifications service instance that you want to authorize.
4. Select the Event Source Manager role.
5. Click Review.
6. Click Assign.
Click Save.

Connecting to Event Notifications with the API

Before you can enable notifications for projects, be sure that you have an Event Notifications service instance that is in the same account as your projects instance. Then, you can connect to Event Notifications programmatically by calling the projects API.

The following example shows a query that you can use to register your projects source details with Event Notifications. When you call the API, replace the ID variables and IAM token with the values that are specific to your projects instance.

You can find the event_notifications_instance_crn value in the console by going to the Resource list page and clicking the Event Notifications instance row.

[enter API example here]

A successful response returns the CRN value of your connected Event Notifications service instance. For more information about the required and optional request parameters, see the API docs.

Delivering notifications to select destinations

After you enable notifications for projects, create topics and subscriptions in Event Notifications so that alerts can be forwarded and delivered to your selected destinations.

For a complete list of supported destinations, see the Event Notifications documentation.

Email notifications

You can use the IBM Cloud email service as a delivery channel for projects event notifications. Create an Event Notifications subscription between an existing topic and the IBM Cloud email service to forward your alerts to various recipients by email.

An email from IBM Cloud that contains information about a projects event resembles the following example:

Subject: Validation successful for terrafrom-1234567890-a12a triggered by IBMid-12345ABCD1
Body: Validation is complete. Review and approve the validation results to deploy the changes.
    Project Service event details:
    Type: check.pipeline.succeeded
    Target: Config terrafrom-1234567890-a12a for Project example-email-notification-project
    Source: pipelinerun-123ab1ab-1a1a-1a11-1a12-ac1a1a12a12a
    Triggered by: IBMid-12345ABCD1
    Action URL: https://cloud.ibm.com/devops/pipelines/example
    Date: Fri April 10 2023 09:15:08 GMT-0500 (Eastern Standard Time)

To receive detailed information about an event notification in your email, select the Add notification payload option when you create an Event Notifications subscription. Your email displays the notification payload details that are associated with the event.

Webhooks

You can configure a webhook destination so that an incoming notification can be consumed programmatically by an app or service. For more information about setting up webhooks, check out the Event Notifications documentation.

Notification payload details

Successful events that are generated by projects contain various fields that help you to identify the source and details of an event.

Event notifications from projects contain only metadata properties, such as names or identifiers of resources. Sensitive data, for example API keys or passwords, are not included in generated events.

The properties that are sent to Event Notifications vary depending on the event type. For example, if an check.pipeline.succeeded event takes place, projects sends a notification payload to Event Notifications that is similar to the following example.

{
      "_id": "a7110265-88e5-4fda-8686-ae4d5bb3f86a",
      "event": "check.pipeline.succeeded",
      "target": "639d4201-8cf9-4e29-b076-5129b6a3f839:1:true",
      "source": "d1542c4b-533c-4276-9272-00ce5134a7a3",
      "triggered_by": "IBMid-test-notification",
      "action_url": "https://cloud.ibm.com/schematics/workspaces/us-south.workspace.projects-service.e7de98e8/jobs?region=us",
      "severity": "INFO",
      "timestamp": "2023-04-10T16:00:43.195Z"
}

Review following table for more information about event notification properties.

Table 2. Properties in an event notification payload
Property	Description
`event_sub_type`	The subtype that corresponds with the type of event that triggered a notification.
`event_type`	The type of event that triggered a notification.
`source_instance_api_url`	The dedicated endpoint URL that is assigned to your IBM Cloud Projects service instance.
`source_instance_crn`	The Cloud Resource Name (CRN) that uniquely identifies your IBM Cloud Projects service instance.
`source_instance_dashboard_url`	The URL to your IBM Cloud Projects service dashboard in the console.
`source_service`	The display name of the service that sent the event notification.