Skip to main content

Notifications

Klarity ImageFactory can automatically notify your external systems whenever an image build or distribution event occurs. This allows you to integrate the platform with your existing CI/CD pipelines, monitoring tools, or communication platforms like Slack and Microsoft Teams.

Notification Types​

ImageFactory supports three primary notification methods, each suited for different integration scenarios.

1. AWS Simple Notification Service (SNS)​

Use SNS to send notifications to subscribed endpoints such as email addresses, HTTP endpoints, or other AWS services.

  • Configuration: Provide the ARN of the target SNS topic.
  • Permissions: Ensure that the ImageFactory AWS account has the sns:Publish permission for the specified topic.

2. Google Cloud Pub/Sub​

Use Pub/Sub for integrations within the Google Cloud ecosystem.

  • Configuration: Provide the full name of the Pub/Sub topic.
  • Permissions: Ensure that the ImageFactory service account has the roles/pubsub.publisher role for the target topic.

3. Webhooks (HTTP POST)​

Webhooks allow you to send a JSON payload to any HTTPS endpoint. This is the most flexible method for integrating with custom applications or third-party services.

  • Configuration: Provide the full HTTPS URL of your endpoint.
  • Headers: You can optionally provide custom HTTP headers (e.g., Authorization or X-API-Key) to authenticate the request.

How Notifications are Triggered​

Notifications are configured within the notifications array of a template. A notification is sent for every successfully distributed image.

  • Granularity: If a template is distributed to 10 different cloud accounts, ImageFactory will send 10 individual notifications. Each notification contains the specific details for that account's distribution.
  • Timing: Notifications are dispatched immediately after the distribution process for an account reaches a terminal state (IMAGE_CREATED or SHARE_ERROR).

Notification Payload​

The notification payload is a JSON object that includes comprehensive information about the build and distribution. Key fields include:

  • Template Info: Name, ID, and provider.
  • Image Info: Build ID, distribution ID, and OS type.
  • Distribution Details: Target account ID, region, and the resulting native image ID.
  • Status: The final status of the distribution (e.g., IMAGE_CREATED).
  • Compliance: The compliance score and a summary of the test results.

Step-by-Step Configuration​

1. Prepare the Target​

Create your SNS topic, Pub/Sub topic, or HTTPS endpoint. Ensure that the necessary permissions or authentication mechanisms are in place.

SNS CloudFormation Template

For AWS SNS notifications, ImageFactory provides a ready-made CloudFormation template that creates the SNS topic with the correct permissions. When you select SNS as the notification type in the template editor, a download link for the template is displayed. Deploy it in your AWS account to create a properly configured topic — no manual permission setup required.

2. Configure Notifications in the Web Interface​

Notifications are configured during template creation in the Basic Settings step, or by editing an existing template. In the Notifications section, select the notification type and provide the required endpoint details.

For a detailed walkthrough, see the Creating a Template guide.

3. Verify the Integration​

Trigger a build for the template and monitor your target system for the incoming notification payload.

Via API

You can also configure notifications programmatically using the GraphQL API:

mutation CreateTemplateWithNotifications {
  createTemplate(input: {
    name: "Secure-Linux-Image"
    provider: AWS
    distributionId: "ubuntu-22.04-lts"
    notifications: [
      {
        type: SNS
        uri: "arn:aws:sns:eu-west-1:123456789012:ImageFactoryEvents"
      },
      {
        type: WEB_HOOK
        uri: "https://api.yourcompany.com/v1/webhooks/image-factory"
        headers: [
          { key: "Authorization", value: "Bearer your-secret-token" }
        ]
      }
    ]
    # ... other template settings
  }) {
    id
    status
  }
}

Best Practices​

  • Use HTTPS: Always use HTTPS for webhook URLs to ensure that the notification payload is encrypted during transit.
  • Implement Authentication: Use custom headers for webhooks to verify that the incoming requests are actually from ImageFactory.
  • Idempotency: Design your receiving system to handle duplicate notifications gracefully, as network retries may occasionally cause the same event to be sent more than once.

By configuring automated notifications, you can ensure that your downstream systems and teams are always aware of the latest golden images available for deployment.