Alerting

API reference for Cloudflare Alerting (notifications and alerts)

Overview

Cloudflare Alerting sends notifications when events occur on your Cloudflare account or zones. Manage alert policies, notification destinations, and view alert history.

Initialize the client

import Cloudflare from 'cloudflare';

const client = new Cloudflare({
  apiToken: 'your-api-token',
});

Policies

Manage alert policies.

Create a policy

Create a new alert policy.

const policy = await client.alerting.policies.create({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
  name: 'SSL Certificate Expiring',
  alert_type: 'universal_ssl_event_type',
  enabled: true,
  mechanisms: {
    email: [{ id: '[e-mail]' }],
  },
});

account_id · string · required

Account identifier

name · string · required

Policy name

alert_type · string · required

Type of alert (e.g., universal_ssl_event_type, dos_attack_l7, health_check_status_notification)

enabled · boolean · required

Whether the policy is active

mechanisms · object · required

Notification mechanisms (email, webhook, PagerDuty, etc.)

filters · object

Conditions that trigger the alert

id · string

Policy identifier

name · string

Policy name

created · string

When the policy was created

modified · string

When the policy was last modified

Update a policy

Update an existing alert policy.

const policy = await client.alerting.policies.update(
  policyId,
  {
    account_id: '023e105f4ecef8ad9ca31a8372d0c353',
    enabled: false,
  }
);

List policies

List all alert policies.

const policies = await client.alerting.policies.list({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
});

Get a policy

Get details of a specific alert policy.

const policy = await client.alerting.policies.get(
  policyId,
  { account_id: '023e105f4ecef8ad9ca31a8372d0c353' }
);

Delete a policy

Delete an alert policy.

await client.alerting.policies.delete(
  policyId,
  { account_id: '023e105f4ecef8ad9ca31a8372d0c353' }
);

Destinations

Manage notification destinations.

const destinations = client.alerting.destinations;

Destinations define where alerts are sent (email, webhook, PagerDuty, Slack, etc.).

History

View alert history.

List alert history

Retrieve a history of triggered alerts.

const history = await client.alerting.history.list({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
});

account_id · string · required

Account identifier

since · string

Filter alerts since this timestamp

before · string

Filter alerts before this timestamp

id · string

Alert history identifier

name · string

Alert name

alert_type · string

Type of alert

triggered_at · string

When the alert was triggered

Silences

Manage alert silences (temporarily disable alerts).

Create a silence

Create a new alert silence.

const silence = await client.alerting.silences.create({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
  description: 'Maintenance window',
  start: '2024-01-01T00:00:00Z',
  end: '2024-01-01T04:00:00Z',
});

account_id · string · required

Account identifier

description · string · required

Silence description

start · string · required

Start time (ISO 8601 format)

end · string · required

End time (ISO 8601 format)

Update a silence

const silence = await client.alerting.silences.update(
  silenceId,
  params
);

List silences

const silences = await client.alerting.silences.list({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
});

Get a silence

const silence = await client.alerting.silences.get(
  silenceId,
  { account_id: '023e105f4ecef8ad9ca31a8372d0c353' }
);

Delete a silence

await client.alerting.silences.delete(
  silenceId,
  { account_id: '023e105f4ecef8ad9ca31a8372d0c353' }
);

Available alerts

Get information about available alert types.

List available alerts

const alerts = await client.alerting.availableAlerts.list({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
});

type · string

Alert type identifier

display_name · string

Human-readable alert name

description · string

Alert description

Types

Mechanism

Notification delivery mechanism.

email · array

Email addresses to notify

webhooks · array

Webhook URLs to call

pagerduty · array

PagerDuty integration keys

PolicyFilter

Conditions for triggering alerts.

zones · string[]

Zone IDs to monitor

health_check_id · string

Health check identifier (for health check alerts)