You're viewing **Apigee Edge** documentation.  
[Go to the
**Apigee X** documentation](http://cloud.google.com/apigee/docs/api-monitoring/alerts-notifications). info

> [!NOTE]
> **Note:** This content currently in Beta. See [Release Stages](https://docs.apigee.com/release/release-stages) for more about a Beta.

Use a TLS expiry [alert](https://docs.apigee.com/api-monitoring/alerts-notifications) to raise
a notification when TLS cert in an environment is about to expire.

> [!WARNING]
> **Known issue:** The triggering of expiry alerts may be inconsistent. For example, you may notice that an alert was not triggered as expected.

## About TLS certs

TLS (Transport Layer Security) is the standard security technology
for establishing an encrypted link between a web server and a web client, such as a browser or an
app. An encrypted link ensures that all data passing between the server and the client remains
private.

A TLS cert is a digital file that identifies an entity in a TLS transaction. Edge uses a TLS
cert to configure TLS for:

- Access to your API proxies by API clients. Use [virtual hosts](https://docs.apigee.com/api-platform/system-administration/configuring-ssl-access-api-cloud-based-edge-installation) to configure TLS.
- Access to your backend services by Edge. Use [target endpoints and target servers](https://docs.apigee.com/api-platform/system-administration/configuring-ssl-edge-backend-service) on the Edge Message Processor to configure TLS.

A TLS cert contains an expiration date. If a TLS cert expires, the TLS connection fails
until you update the cert. That means all requests to your API will fail until you update the cert.

## About expiry alerts

Rather than waiting for a cert to expire, and for requests to your API to fail, use an
expiry [alert](https://docs.apigee.com/api-monitoring/alerts-notifications) to raise
a notification when any TLS cert in an environment is about to expire.
After the alert is triggered, you can update the cert so that your customers will not
see any interruption in service.

When configuring the alert, do not specify an individual cert, but a specific environment.
The alert is triggered when any cert deployed is scheduled
to expire within the specified time range.

You can set the expiry alert to occur:

- 1 day before any cert is to expire
- 14 days before any cert is to expire
- 30 days before any cert is to expire

For more on alerts, see [Set up alerts and notifications](https://docs.apigee.com/api-monitoring/alerts-notifications).

## Add expiry alerts and notifications

To add expiry alerts and notifications:

1. Click **Analyze \> Alert Rules** in the Edge UI.
2. Click **+Alert**.
3. Enter the following general information about the alert:

   | Field | Description |
   |---|---|
   | Alert Name | Name of the alert. Use a name that describes the trigger and that will be meaningful to you. The name cannot exceed 128 characters. |
   | Description | Description of the alert. |
   | Alert Type | Select **TLS Expiry** . See [About alert types](https://docs.apigee.com/api-monitoring/alerts-notifications#fixed_expiry) for more. |
   | Environment | Select the environment from the drop-down list. |
   | Status | Toggle to enable or disable the alert. |

4. Define the threshold and dimension for the condition that will trigger the alert.

   | Condition Field | Description |
   |---|---|
   | Threshold | Configure time range for the expiring certs. You can choose to raise an alert when a cert is going to expire in: - 1 day - 14 days - 30 days |
   | Dimension | The dimensions is fixed to a value of **Any TLS Certificates** corresponding to any TLS cert in the environment. |

5. Click **+ Notification** to add an alert notification.

   | Notification Details | Description |
   |---|---|
   | Channel | Select the notification channel that you want to use and specify the destination: Email, Slack, PagerDuty, or Webhook. |
   | Destination | Specify the destination based on the selected channel type: - Email - Email address, such as `joe@company.com` - Slack - Slack channel URL, such as `https://hooks.slack.com/services/T00000000/B00000000/XXXXX` - PagerDuty - PagerDuty code, such as `abcd1234efgh56789` - Webhook - Webhook URL, such as `https://apigee.com/test-webhook` **Note**: You can specify only one destination per notification. To specify multiple destinations for the same channel type, add additional notifications. |

6. To add additional notifications, repeat the previous step.
7. If you added a notification, set the following fields:

   | Field | Description |
   |---|---|
   | Playbook | (Optional) Free-form text field to provide a short description of recommended actions for resolving the alerts when they fire. You can also specify a link to your internal wiki or community page where you reference best practices. The information in this field will be included in the notification. The contents in this field cannot exceed 1500 characters. |
   | Throttle | Frequency with which to send notifications. Select a value from the drop-down list. |

8. Click **Save**.

## View alerts in the Events dashboard

When Edge detects an alert condition, it automatically logs that condition to the
**Events** dashboard in the Edge UI. The list of events displayed in the Events dashboard
includes all alerts, both fixed and cert.

To view an alert:

1. Click **Analyze \> Events** in the Edge UI. The new Events dashboard appears:

2. Filter the Events dashboard by:

   - Environment
   - Region
   - Time period
3. Select a row in the Event dashboard to show the Keystore containing the expiring cert to further investigate the alert. From the Keystore page, you can upload a new cert and delete the expiring cert.

## Use the alert APIs with expiry alerts

Most of the APIs that you use to create and manage expiry alerts are the same as the ones you use
with fixed alerts. The following alert APIs work in the same way for both fixed and expiry alerts:

- [Get an alert](https://apidocs.apigee.com/docs/alerts/1/routes/alerts/%7BalertId%7D/get) - Get a fixed or anomaly alert definition.
- [Get alert history](https://apidocs.apigee.com/docs/metrics/1/routes/alerthistory/get) - Get alert history metrics.
- [Delete an alert](https://apidocs.apigee.com/docs/alerts/1/routes/alerts/%7BalertId%7D/delete) - Delete a fixed or anomaly alert definition.
- [Get alert instance](https://apidocs.apigee.com/docs/metrics/1/routes/alertinstance/%7Binstance_id%7D/get) - Get information about a triggered alert.
- [Get alert count](https://apidocs.apigee.com/docs/metrics/1/routes/alertsummary/get) - Get the total count of alerts.

However, some APIs have additional properties used to support anomaly alerts, including:

- [Get alerts](https://apidocs.apigee.com/docs/alerts/1/routes/alerts/get) - List all alerts, including fixed and anomaly alerts.
- [Create an alert](https://apidocs.apigee.com/docs/alerts/1/routes/alerts/post) - Create a fixed or anomaly alert.
- [Update an alert](https://apidocs.apigee.com/docs/alerts/1/routes/alerts/%7BalertId%7D/put) - Update a fixed or anomaly alert definition.

### Create or update an expiry alert

Use the same APIs to [create](https://apidocs.apigee.com/docs/alerts/1/routes/alerts/post)
or [update](https://apidocs.apigee.com/docs/alerts/1/routes/alerts/%7BalertId%7D/put)
an expiry alert as you currently do for a fixed alert. The body of the API call to create or update
an expiry alert is the same as used for a fixed alert, with the following changes:

- You must add the following new properties to specify that the alert is an expiry alert:

  ```
  "alertType": "cert"
  "alertSubType": "certfixed"
  ```

  The default values of these properties are:

  ```
  "alertType": "runtime"
  "alertSubType": "fixed"
  ```
- In the `conditions` array:

  - The `metrics` property only takes the values of `expiration`.
  - Use the `gracePeriodSeconds` property to specify the time range of the cert expiration in seconds, to a maximum duration of 30 days.
  - The `threshold`, `durationSeconds`, and `comparator` properties are not supported.
- In the `dimensions` element of the `conditions` array:
  - You must set the value of the `certificate` property to `ANY`.
  - You must set the value of the `proxy` property to `ALL`.
  - The `statusCode`, `developerApp`, `collection`, `faultCodeCategory`, `faultCodeSubCategory`, `faultCodeName` properties are not supported.
- The `reportEnabled` property is not supported for expiry alerts.

The following example API call creates an expiry alert that is triggered when any cery in the
prod environment will expire in the next 30 days. A notification is sent to the specified email address
when the alert is triggered:

```
curl 'https://apimonitoring.enterprise.apigee.com/alerts' \
 -X POST \
 -H 'Accept: application/json, text/plain, */*' -H "Content-Type: application/json" \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -d '{
  "organization":"myorg",
  "name":"My Cert Expiry Alert",
  "description":"My Cert Expiry Alert",
  "environment":"prod",
  "enabled":true,
  "alertType": "cert",
  "alertSubType": "certfixed",
  "conditions":[
  {
    "description":"My Cert Expiry Alert",
    "dimensions":{
      "org":"myorg",
      "env":"prod",
      "proxy":"ALL",
      "certificate": "ANY"
    },
    "metric":"expiration",
    "gracePeriodSeconds": 2592000
  }],
  "notifications":[{
    "channel":"email",
    "destination":"ops@acme.com"
  }],
  "playbook":"http://acme.com/pb.html",
  "throttleIntervalSeconds":3600,
  "reportEnabled":false
}'
```

Set `$ACCESS_TOKEN` to your OAuth 2.0 access token, as described in
[Obtain an OAuth 2.0 access token](https://docs.apigee.com/api-monitoring/api#oauth2).
For information about the cURL options used in this example, see [Use cURL](https://docs.apigee.com/api-monitoring/api#curl).

### Get expiry alerts

By default, the [Get Alerts](https://apidocs.apigee.com/docs/alerts/1/routes/alerts/get) API
returns information about all defined alerts, both fixed and expiry. This API now takes query parameters to let you filter the results:

- `enabled` - If `true` specifies to return only enabled alerts. The default value is `false`.
- `alertType` - Specifies the type of alert to return. The allowed values are `runtime`, the default, and `cert`.
- `alertSubType` - Specifies the alert subtype to return. The default value is unset, meaning return all alert subtypes. Specify `certfixed` to return expiry alerts.

For example, use the following API call to return only enable alerts for the organization named `myorg`:

```
curl -H "Authorization: Bearer $ACCESS_TOKEN" \
'https://apimonitoring.enterprise.apigee.com/alerts?org=myorg&enabled=true'
```

The following call returns only expiry alerts, both enabled and disabled:

```
curl -H "Authorization: Bearer $ACCESS_TOKEN" \
'https://apimonitoring.enterprise.apigee.com/alerts?org=myorg&alertType=cert&alertSubType=certfixed'
```

Set `$ACCESS_TOKEN` to your OAuth 2.0 access token, as described in
[Obtain an OAuth 2.0 access token](https://docs.apigee.com/api-monitoring/api#oauth2).
For information about the cURL options used in this example, see [Use cURL](https://docs.apigee.com/api-monitoring/api#curl).