---
description: Review the JSON payload structure for webhooks.
title: Webhook payload schema
image: https://developers.cloudflare.com/og-docs.png
---

[Skip to content](#main-content)

> Documentation Index  
> Fetch the complete documentation index at: https://developers.cloudflare.com/notifications/llms.txt  
> Use this file to discover all available pages before exploring further.

# Webhook payload schema

Last updated Sep 1, 2026|Copy as Markdown| [View as Markdown](https://0285ca83.previews.developers.cloudflare.com/notifications/reference/webhook-payload-schema/index.md)| [Agent setup](https://0285ca83.previews.developers.cloudflare.com/agent-setup/)

When you [configure a generic webhook](https://0285ca83.previews.developers.cloudflare.com/notifications/get-started/configure-webhooks/#generic-webhooks), Cloudflare sends a JSON payload to your specified URL for each notification. This page documents the structure of that payload.

## Payload structure

All generic webhook notifications follow this schema:

```json
{
	"name": "string",
	"text": "string",
	"data": {},
	"ts": 1136214245,
	"account_id": "string",
	"policy_id": "string",
	"policy_name": "string",
	"alert_type": "string",
	"alert_correlation_id": "string",
	"alert_event": "string"
}
```

### Field descriptions

| Field | Type | Description |
| --- | --- | --- |
| `name` | string | The name of the notification policy. |
| `text` | string | A human-readable description of the notification with interpolated values. |
| `data` | object | The alert-specific data. The structure varies by `alert_type`. |
| `ts` | integer | The unix timestamp (seconds since epoch, UTC) when the notification was generated. |
| `account_id` | string | The account ID for which this webhook was fired. |
| `policy_id` | string | The UUID of the notification policy that triggered this webhook. |
| `policy_name` | string | The name of the notification policy. |
| `alert_type` | string | The unique identifier for the alert type (for example, `http_alert_origin_error`). |
| `alert_correlation_id` | string | The UUID that groups related alerts together. |
| `alert_event` | string | The event state, such as `ALERT_STATE_EVENT_START` or `ALERT_STATE_EVENT_END`. |

Note

The `account_id`, `policy_id`, and `alert_type` fields may not be present in all notifications, depending on the alert type and context.

## Example payloads

The following examples show the payload structure for common alert types. The `data` object varies based on the specific alert.

<details>

<summary>

DDoS attack (Layer 4)

</summary>

```json
{
	"account_id": "9035f53656c247e895c5a6939ae8a0e0",
	"alert_correlation_id": "000eaa907ed24e78946d3a93adb2ae57",
	"alert_event": "ALERT_STATE_EVENT_START",
	"alert_type": "advanced_ddos_attack_l4_alert",
	"data": {
		"account_name": "string",
		"account_tag": "string",
		"action": "string",
		"attack_id": "string",
		"attack_vector": "string",
		"dashboard_link": "string",
		"max_rate": "string",
		"megabits_per_second": 0,
		"mitigation": "string",
		"packets_per_second": 0,
		"protocol": "string",
		"rule_description": "string",
		"rule_id": "string",
		"rule_name": "string",
		"ruleset_id": "string",
		"ruleset_override_id": "string",
		"start_time": "2006-01-02T15:04:05Z",
		"target_id": "string",
		"target_ip": "string",
		"target_port": 0
	},
	"name": "Example Cloudflare Notification",
	"policy_id": "749b911ea5d04344a58e45edd099b328",
	"policy_name": "Example Cloudflare Notification",
	"text": "The description of my Cloudflare notification.",
	"ts": 1136214245
}
```

</details>

<details>

<summary>

DDoS attack (Layer 7)

</summary>

```json
{
	"account_id": "9035f53656c247e895c5a6939ae8a0e0",
	"alert_correlation_id": "000eaa907ed24e78946d3a93adb2ae57",
	"alert_event": "ALERT_STATE_EVENT_START",
	"alert_type": "advanced_ddos_attack_l7_alert",
	"data": {
		"account_name": "string",
		"account_tag": "string",
		"action": "string",
		"attack_id": "string",
		"attack_type": "string",
		"dashboard_link": "string",
		"max_rate": "string",
		"mitigation": "string",
		"requests_per_second": 0,
		"rule_description": "string",
		"rule_id": "string",
		"rule_link": "string",
		"ruleset_id": "string",
		"ruleset_override_id": "string",
		"start_time": "2006-01-02T15:04:05Z",
		"target_hostname": "string",
		"zone_name": "string",
		"zone_tag": "string"
	},
	"name": "Example Cloudflare Notification",
	"policy_id": "749b911ea5d04344a58e45edd099b328",
	"policy_name": "Example Cloudflare Notification",
	"text": "The description of my Cloudflare notification.",
	"ts": 1136214245
}
```

</details>

<details>

<summary>

SSL certificate expiration

</summary>

```json
{
	"account_id": "9035f53656c247e895c5a6939ae8a0e0",
	"alert_correlation_id": "000eaa907ed24e78946d3a93adb2ae57",
	"alert_event": "ALERT_STATE_EVENT_START",
	"alert_type": "dedicated_ssl_certificate_event_type",
	"data": {
		"account_name": "string",
		"account_tag": "string",
		"certificate_id": "string",
		"certificate_pack_id": "string",
		"certificate_status": "string",
		"event_type": "string",
		"hostnames": "string",
		"pack_ca": "string",
		"pack_id": "string",
		"pack_status": "string",
		"pack_validation": "string",
		"zone_name": "string",
		"zone_tag": "string"
	},
	"name": "Example Cloudflare Notification",
	"policy_id": "749b911ea5d04344a58e45edd099b328",
	"policy_name": "Example Cloudflare Notification",
	"text": "The description of my Cloudflare notification.",
	"ts": 1136214245
}
```

</details>

<details>

<summary>

Origin health check

</summary>

```json
{
	"account_id": "9035f53656c247e895c5a6939ae8a0e0",
	"alert_correlation_id": "000eaa907ed24e78946d3a93adb2ae57",
	"alert_event": "ALERT_STATE_EVENT_START",
	"alert_type": "health_check_status_notification",
	"data": {
		"account_name": "string",
		"account_tag": "string",
		"failing_regions": "string",
		"health_check_id": "string",
		"health_check_name": "string",
		"new_health_status": "string",
		"new_status": "string",
		"old_status": "string",
		"origin_ip": "string",
		"reason": "string",
		"status_change_time": "2006-01-02T15:04:05Z",
		"time_since_last_failure": "string",
		"zone_name": "string",
		"zone_tag": "string"
	},
	"name": "Example Cloudflare Notification",
	"policy_id": "749b911ea5d04344a58e45edd099b328",
	"policy_name": "Example Cloudflare Notification",
	"text": "The description of my Cloudflare notification.",
	"ts": 1136214245
}
```

</details>

<details>

<summary>

Workers alert

</summary>

```json
{
	"account_id": "9035f53656c247e895c5a6939ae8a0e0",
	"alert_correlation_id": "000eaa907ed24e78946d3a93adb2ae57",
	"alert_event": "ALERT_STATE_EVENT_START",
	"alert_type": "workers_alert",
	"data": {
		"account_name": "string",
		"account_script_count": 0,
		"account_tag": "string",
		"alert_type": "string",
		"current_year": 0,
		"end_date": "string",
		"exceeding_script_count": 0,
		"scripts": [
			{
				"constant_script_id": 0,
				"cpu_time_previous_value": 0,
				"cpu_time_unit": "string",
				"cpu_time_value": 0,
				"data_egress_unit": "string",
				"data_egress_value": 0,
				"duration_previous_value": 0,
				"duration_unit": "string",
				"duration_value": 0,
				"last_modified": "string",
				"request_count_previous_value": 0,
				"request_count_unit": "string",
				"request_count_value": 0,
				"routes": ["string"],
				"script_name": "string",
				"usage_model": 0
			}
		],
		"start_date": "string",
		"total_data_egress_unit": "string",
		"total_data_egress_value": 0,
		"total_duration_unit": "string",
		"total_duration_value": 0,
		"total_request_count_unit": "string",
		"total_request_count_value": 0
	},
	"name": "Example Cloudflare Notification",
	"policy_id": "749b911ea5d04344a58e45edd099b328",
	"policy_name": "Example Cloudflare Notification",
	"text": "The description of my Cloudflare notification.",
	"ts": 1136214245
}
```

</details>

<details>

<summary>

Access certificate expiration

</summary>

```json
{
	"account_id": "9035f53656c247e895c5a6939ae8a0e0",
	"alert_correlation_id": "000eaa907ed24e78946d3a93adb2ae57",
	"alert_event": "ALERT_STATE_EVENT_START",
	"alert_type": "access_custom_certificate_expiration_type",
	"data": {
		"account_name": "string",
		"account_tag": "string",
		"certificate_id": "string",
		"days_til_expiration": 0,
		"hostnames": "string",
		"zone_name": "string",
		"zone_tag": "string"
	},
	"name": "Example Cloudflare Notification",
	"policy_id": "749b911ea5d04344a58e45edd099b328",
	"policy_name": "Example Cloudflare Notification",
	"text": "The description of my Cloudflare notification.",
	"ts": 1136214245
}
```

</details>

<details>

<summary>

Workers observability alert

</summary>

```json
{
	"account_id": "9035f53656c247e895c5a6939ae8a0e0",
	"alert_correlation_id": "000eaa907ed24e78946d3a93adb2ae57",
	"alert_event": "ALERT_STATE_EVENT_START",
	"alert_type": "workers_observability_alert",
	"data": {
		"account": {
			"id": "string",
			"name": "string"
		},
		"config": {
			"id": "string",
			"name": "string"
		},
		"episode": {
			"first_failed": "2006-01-02T15:04:05Z",
			"first_fired": "2006-01-02T15:04:05Z",
			"id": "string",
			"last_failed": "2006-01-02T15:04:05Z",
			"resolved_at": "2006-01-02T15:04:05Z",
			"summary": "string"
		},
		"status": "PENDING"
	},
	"name": "Example Cloudflare Notification",
	"policy_id": "749b911ea5d04344a58e45edd099b328",
	"policy_name": "Example Cloudflare Notification",
	"text": "The description of my Cloudflare notification.",
	"ts": 1136214245
}
```

</details>

## Validate webhook payloads

You can use the `cf-webhook-auth` header to verify that incoming webhooks are from Cloudflare. When you configure a webhook with a secret, Cloudflare includes this header with your secret value in every request. Reject any requests where this header is missing or does not match your configured secret.

## Related resources

- [Configure webhooks](https://0285ca83.previews.developers.cloudflare.com/notifications/get-started/configure-webhooks/)
- [Available notification types](https://0285ca83.previews.developers.cloudflare.com/notifications/notification-available/)

Was this helpful?

YesNo

## On this page

[![](https://0285ca83.previews.developers.cloudflare.com/_astro/logo.te5VL_aD.svg)Docs](https://0285ca83.previews.developers.cloudflare.com/)

```json
{"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/notifications/reference/webhook-payload-schema/#page","headline":"Webhook payload schema · Cloudflare Notifications docs","description":"Review the JSON payload structure for webhooks.","url":"https://developers.cloudflare.com/notifications/reference/webhook-payload-schema/","inLanguage":"en","image":"https://developers.cloudflare.com/og-docs.png","dateModified":"2026-09-01","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}}
```