Skip to content

Event notification types

See the following sections for the type of notification you're configuring. Each section lists the event type identifier and includes example Common Expression Language (CEL) expressions.

Common Expression Language (CEL) introduction

The Common Expression Language (CEL) uses a simple syntax similar to expressions in C++, Java, JavaScript, and Go. CEL expressions are usually concise, single-line statements that evaluate to a single value. If the evaluation result is true, the system triggers a notification to the specified integration. If the evaluation result is false, the system takes no action.

Inputs to a CEL expression are called variables. Each field within the event can be a variable in the CEL expression. CEL comes with standard language functions as defined in the official specification.

cert-manager issuer resource events

The following syntax defines the event type and event type identifier for cert-manager issuer events:

event type: evt.healthstatus.cert-manager-issuer (use in CEL expressions)

event type identifier: cert-manager-issuer-health-notification-config (use in API)

cert-manager unhealthy status for issuer resource

Use the following event data fields for CEL expressions for filtering to find certificates with unhealthy issuer status. For example:

{
  "type": "evt.healthstatus.cert-manager-issuer.notready",
  "data": {
    "clusterId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "clusterName": "demo-cluster",
    "issuerName": "demo-issuer",
    "namespace": "demo-namespace",
    "resourceId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "statusMessage": "Failed to register ACME account: Get \"https://invalid-url\": dial tcp: lookup invalid-url on 10.96.0.10:53: no such host",
    "statusReason": "ErrRegisterACMEAccount",
    "statusTransition": "2025-03-05T15:53:51Z"
  }
}

Advanced CEL expression examples

Use the following examples to create API requests for router configurations using the event type identifier cert-manager-issuer-health-notification-config.

Unhealthy issuer CEL expression examples:

  • To match all cert-manager unhealthy and healthy state restored events, use the cert-manager-issuer-health-notification-config event type identifier

  • To match only unhealthy certificate manager issuer notifications, use the same event type identifier with this CEL expression:

    type.endsWith('.notready')

  • To match issuers in an unhealthy state for specific clusters, use the same event type identifier with this CEL expression:

    type.endsWith('.notready') && (data.clusterId == 'clusterID-1' || data.clusterId == 'clusterID-2')

  • Tp match unhealthy cert-manager issuer deployed in a specific namespace, use the same event type identifier with this CEL expression:

    type.endsWith('.notready') && (data.namespace == 'demo-namespace')

cert-manager issuer resource healthy state restored

Use the following event data fields in CEL expressions to filter for restored healthy state events. For example:

{
  "type": "evt.healthstatus.cert-manager-issuer.active",
  "data": {
    "clusterId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "clusterName": "demo-cluster",
    "issuerName": "demo-issuer",
    "namespace": "demo-namespace",
    "resourceId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "statusMessage": "The ACME account was registered with the ACME server",
    "statusReason": "ACMEAccountRegistered",
    "statusTransition": "2025-03-05T16:24:46Z",
    "unhealthyDuration": "30m13.049891s"
  }
}

Advanced CEL expression examples

To match all unhealthy and healthy state restored events, use the cert-manager-issuer-health-notification-config event type identifier.

  • For all cert-manager issuer notifications in the restored state, use the cert-manager-issuer-health-notification-config event type identifier with this CEL expression:

    type.endsWith('.active')

  • To find a specific issuer restored to healthy status, use the same event type identifier with this CEL expression:

    type.endsWith('.active') && data.issuerName == 'my-issuer'

cert-manager certificate resource events

The following defines the event type and event type identifier for cert-manager resource events

event type: evt.healthstatus.cert-manager-certificate-resource (use in CEL expressions)

event type identifier: cert-manager-cert-resource-health-notification-config (use in API)

cert-manager unhealthy status for certificate resource

Use the following event data fields for CEL expressions for filtering to find certificates with unhealthy status for certificate resource. For example:

{
 "type": "evt.healthstatus.cert-manager-certificate-resource.notready",
 "data": {
  "clusterName": "My Cluster",
  "clusterId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "certificateName": "test-cert",
  "namespace": "my-namespace",
  "issuerName": "missing-issuer",
  "statusMessage": "Issuing certificate as Secret does not exist",
  "unhealthyDuration": "166h51m46.031628918s",
  "statusReason": "DoesNotExist",
  "statusTransition": "2025-02-10T08:12:22Z",
  "subject": {
   "commonName": "example-service",
   "countries": [
    "US"
   ],
   "localities": [
    "South Lake City"
   ],
   "organizationalUnits": [
    "Engineering"
   ],
   "organizations": [
    "example.com"
   ],
   "provinces": [
    "Utah"
   ]
  },
  "SANs": {
   "DNS Names": [ 
    "example.com" 
   ]
  }
 }
}

Advanced CEL expression examples

To match all cert-manager unhealthy and healthy state restored events, use the cert-manager-cert-resource-health-notification-config event type identifier.

  • To match all cert-manager certificate resource unhealthy notifications, configure the event type identifier as cert-manager-cert-resource-health-notification-config and use the following CEL expression:

    type.endsWith('.notready')

  • To match only unhealthy certificate resource events for My Cluster, use the same event type identifier with this CEL expression:

    type.endsWith('.notready') && data.clusterName == 'My Cluster'

cert-manager certificate resource healthy state restored

Use the following details of the event data that are available for filtering purposes in your CEL expression. See below the data example for specific examples.

{
 "type": "evt.healthstatus.cert-manager-certificate-resource.active",
    "data": {
      "SANs": {},
      "certificateName": "example-cert",
      "clusterId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "clusterName": "My Cluster",
      "issuerName": "my-selfsigned-issuer",
      "namespace": "default",
      "resourceId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "statusMessage": "Certificate is up to date and has not expired",
      "statusReason": "Ready",
      "statusTransition": "2025-03-06T15:48:33Z",
      "subject": {
        "commonName": "example-service",
        "countries": [
          "US"
        ],
        "localities": [
          "South Lake City"
        ],
        "organizationalUnits": [
          "Engineering"
        ],
        "organizations": [
          "My Company"
        ],
        "provinces": [
          "Utah"
        ],
      },
      "unhealthyDuration": "6m24.21461s"
    }
}

Advanced CEL expression examples

To match healthy and unhealthy state restored events, use the cert-manager-cert-resource-health-notification-config event type identifier.

  • To match all cert-manager certificate resource healthy state restored, use the cert-manager-cert-resource-health-notification-config event type identifier, and use the following CEL expression:

    type.endsWith('.active')

  • All cert-manager certificate resource healthy notifications for My Cluster, in addition to the event type identifier:

    type.endsWith('.active') && data.clusterName == 'My Cluster'

Certificate expiration

To get notifications about expired certificates, enable the certificate monitoring service in Venafi Control Plane Policy settings. After you verify your monitoring service configuration, set up the routing for the notifications in either the Notification Center or the notification channel API.

Enable and configure the global certificate monitoring service

Note

You can configure monitoring in the Venafi Control Plane UI. Changes made to the monitoring configuration affect both email and webhook notifications.

Before making any changes to the global configuration, first view the current configuration to see what you need to update.

Send the following API request to view the current configuration:

GET https://api.venafi.cloud/outagedetection/v1/inventorymonitoringconfig/CERTIFICATE_EXPIRATION
tppl-api-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

The response body should look something like this:

{
  "id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "companyId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "configuration":{
    "inventoryMonitoringConfigurationType":"CERTIFICATE_EXPIRATION",
    "enabled":false,
    "thresholds":[],
    "applicationIds":[],
    "includeUnassignedCertificates":false
  }
}

Parameter descriptions

  • id: The unique ID of this inventory monitoring configuration.
  • companyId: The unique ID of your company.
  • inventoryMonitoringConfigurationType: The configuration type. For the purposes of this guide, the value should be CERTIFICATE_EXPIRATION.
  • enabled: Boolean that enables or disables this inventory monitor.
  • thresholds: Array of certificate expiration thresholds, in days. Limit is 3 values.
  • applicationIds: Array of application IDs that the webhook applies to. If blank, all the system monitors all applications. Notifications aren't sent for applications that aren't monitored, even if you specify the application in the webhook configuration (below). For best results, you should monitor all applications.
  • includeUnassignedCertificates: Boolean that enables or disables notifications for certificates that aren't assigned to an application.

Now that you've viewed the current configuration, you can edit and enable it. In this example, you can see how to do the following:

  • Enable certificate monitoring
  • Set notification thresholds of 5, 30, and 90 days
  • Specify two application IDs that this configuration should apply to
  • Disable notifications for unassigned certificates

Start by sending the following request:

PUT https://api.venafi.cloud/outagedetection/v1/inventorymonitoringconfig/CERTIFICATE_EXPIRATION
tppl-api-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Content-Type: application/json

{
  "inventoryMonitoringConfiguration":{
    "inventoryMonitoringConfigurationType":"CERTIFICATE_EXPIRATION",
    "enabled":true,
    "thresholds":[
      5,
      30,
      90
    ],
    "applicationIds":[
      "4b7e4cd0-9009-11ed-95eb-4397cbb5e509",
      "56c28f10-9009-11ed-bb6f-1142ca678b4b"
    ],
    "includeUnassignedCertificates":false
  }
}
Additional request body examples

Monitor all applications:

{
  "inventoryMonitoringConfiguration":{
    "inventoryMonitoringConfigurationType":"CERTIFICATE_EXPIRATION",
    "enabled":true,
    "thresholds":[
     5,
     30,
     90
    ],
    "applicationIds":[

    ],
    "includeUnassignedCertificates":true
  }
}

Monitor only certificates assigned to any application:

{
  "inventoryMonitoringConfiguration":{
    "inventoryMonitoringConfigurationType":"CERTIFICATE_EXPIRATION",
    "enabled":true,
    "thresholds":[
     5,
     30,
     90
    ],
    "applicationIds":[

    ],
    "includeUnassignedCertificates":false
  }
}

Monitor certificates assigned to specific applications and certificates that are not assigned to any application:

{
  "inventoryMonitoringConfiguration":{
    "inventoryMonitoringConfigurationType":"CERTIFICATE_EXPIRATION",
    "enabled":true,
    "thresholds":[
     5,
     30,
     90
    ],
    "applicationIds":[
      "application-id-1",
      "application-id-2"

    ],
    "includeUnassignedCertificates":true
  }
}

Setting up the routing configuration

Event details:

{
  "type": "evt.policy.expiringcertificates.failed",
  "data": {
    "name": "Certificate Expiration Notification",
    "applicationIds": [
      "6ab46c90-acd7-11ef-8b23-f5be1d4bb686"
    ],
    "message": "Certificate Example.com, with id: 6f42f560-acd7-11ef-a386-5be8e97f7088, serial number: 00853F3D26CE90A8007B170DF85462F285, issued by: cn=example.com - 177115678443066294238404735833232044677,o=Example Co., assigned to: [Example-App] has 29 day(s) until expiration. Valid until: 2025-01-01 01:01:01. Please renew and provision the certificate to avoid a potential outage.",
    "notificationDate": "2024-11-27T16:38:38.212+00:00",
    "threshold": 30,
    "ruleId": 1
  }
}

Certificate expiration events

The following event types and event type identifiers are available for certificate expiration events 

event type: evt.policy.expiringcertificates (use in CEL expressions)

event type identifier: cert-expiry-ext-notification-config (use in API)

Note on the use of thresholds vs ruleIds

In the events, the threshold is the actual value of the threshold that triggered the event. The ruleId is the rule identifier for that threshold. It is a better practice to use the ruleId in your configuration filter expressions as the actual thresholds might be changed in the monitor configuration, which would effectively disable your notification configuration.

Advanced CEL expression examples

  • All certificate expiration notifications for every monitored application and all threshold rules, use the cert-expiry-ext-notification-config event type identifer

  • Certificate expiration notifications assigned to a particular application, configure the event type identifier as cert-expiry-ext-notification-config and use the following CEL expression:

    '6ab46c90-acd7-11ef-8b23-f5be1d4bb686' in data.applicationIds

  • Certificate expiration notifications triggered by a particular threshold rule, use the same event type identifier with this CEL expression:

    cel data.ruleId == 1

Other useful GraphQL requests

List all configured notification providers:

curl --request POST \
  --url https://api.venafi.cloud/graphql \
  --header 'tppl-api-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "query": "query GetIntegrationsListData { integrations { nodes { id name enabled } } }",
    "operationName": "GetIntegrationsListData"
  }'

Delete a notification provider:

curl --request POST \
  --url https://api.venafi.cloud/graphql \
  --header 'tppl-api-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "query": "mutation DeleteIntegrations($ids: [UUID!]!) { deleteIntegrations(ids: $ids) { ids __typename } }",
    "operationName": "DeleteIntegrations",
    "variables": {
      "ids": [
        "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
      ]
    }
  }'

List routing configurations:

curl --request POST \
  --url https://api.venafi.cloud/graphql \
  --header 'tppl-api-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "query":" query SearchNotificationRoutingConfigurations { searchNotificationRoutingConfigurations { nodes { id name eventType { id displayName } enabled notificationRouterFilterConfig { advancedFilterExpression } } } }",
    "operationName":"SearchNotificationRoutingConfigurations"
  }'

Disable routing configurations (when created using the new API createNotificationRouter):

curl --request POST \
  --url https://api.venafi.cloud/graphql \
  --header 'tppl-api-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "query": "mutation UpdateNotificationRouter($updateNotificationRouterId: UUID!, $updateNotificationRouterConfigurationInput: UpdateNotificationRouterConfigurationInput!) { updateNotificationRouter(id: $updateNotificationRouterId, updateNotificationRouterConfigurationInput: $updateNotificationRouterConfigurationInput) { id enabled } }",
    "operationName": "UpdateNotificationRouter",
    "variables": {
       "updateNotificationRouterId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
       "updateNotificationRouterConfigurationInput": {
          "enabled": false
       }
    }
}'

Disable routing configurations (when created using the old API createNotificationRoutingConfiguration):

curl --request POST \
  --url https://api.venafi.cloud/graphql \
  --header 'tppl-api-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "query": "mutation UpdateNotificationRouter($id: UUID!, $enabled: Boolean) { updateNotificationRoutingConfiguration(id: $id, enabled: $enabled) { id enabled } }",
    "operationName": "UpdateNotificationRouter",
    "variables": {
      "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "enabled": false
    }
  }'

Delete routing configurations:

curl --request POST \
  --url https://api.venafi.cloud/graphql \
  --header 'tppl-api-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
  "query": "mutation DeleteNotificationRouter($ids: [UUID!]) { deleteNotificationRouter(ids: $ids) { ids } }",
  "operationName": "DeleteNotificationRouter",
  "variables": {
     "ids": ["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"]
  }
}'