Cloudflare Docs
Cloudflare for Platforms
Cloudflare for Platforms
Visit Cloudflare for Platforms on GitHub
Set theme to dark (⇧+D)

Webhook data definitions

When you create a webhook notification for SSL for SaaS Custom Hostnames, you may want to automate responses to specific events (certificate issuance, failed validation, etc.).

The following section details the data Cloudflare sends to a webhook destination.

​​ Certificate validation

Before a Certificate Authority will issue a certificate for a domain, the requestor must prove they have control over that domain. This process is known as domain control validation (DCV).

​​ Validation succeeded

{
"metadata": {
"event": {
"id": "<<WEBHOOK_ID>",
"type": "ssl.custom_hostname_certificate.validation.succeeded",
"created_at": "2022-02-09T00:03:28.385080Z"
},
"account": {
"id": "<<ACCOUNT_ID>"
},
"zone": {
"id": "<<ZONE_ID>"
}
},
"data": {
"id": "<<CUSTOM_HOSTNAME_ID>",
"hostname": "blog.com",
"ssl": {
"id": "<<CERTIFICATE_ID>",
"type": "dv",
"method": "cname",
"status": "pending_issuance",
"settings": {
"min_tls_version": "1.2",
"http2": "on"
}
},
"custom_metadata": {
"key1": "value1",
"key2": "value2"
},
"custom_origin_server": "0001.blog.com"
}
}

​​ Validation failed

{
"metadata": {
"event": {
"id": "<<WEBHOOK_ID>",
"type": "ssl.custom_hostname_certificate.validation.failed",
"created_at": "2018-02-09T00:03:28.385080Z"
},
"account": {
"id": "<<ACCOUNT_ID>"
},
"zone": {
"id": "<<ZONE_ID>"
}
},
"data": {
"id": "<<CUSTOM_HOSTNAME_ID>",
"hostname": "blog.com",
"ssl": {
"id": "<<CERTIFICATE_ID>",
"type": "dv",
"method": "cname",
"status": "pending_validation",
"cname": "_ca3-64ce913ebfe74edeb2e8813e3928e359.app.example2.com",
"cname_target": "dcv.digicert.com",
"validation_errors": [
{
"message": "blog.example.com reported as potential risk: google_safe_browsing"
}
],
"settings": {
"min_tls_version": "1.2",
"http2": "on"
}
},
"custom_metadata": {
"key1": "value1",
"key2": "value2"
},
"custom_origin_server": "0001.blog.com"
}
}

​​ Certificate issuance

Once validated, certificates are issued by Cloudflare in conjunction with your chosen certificate authority.

​​ Issuance succeeded

{
"metadata": {
"event": {
"id": "<<WEBHOOK_ID>",
"type": "ssl.custom_hostname_certificate.issuance.succeeded",
"created_at": "2022-02-09T00:03:28.385080Z"
},
"account": {
"id": "<<ACCOUNT_ID>"
},
"zone": {
"id": "<<ZONE_ID>"
}
},
"data": {
"id": "<<CUSTOM_HOSTNAME_ID>",
"hostname": "blog.com",
"ssl": {
"id": "<<CERTIFICATE_ID>",
"type": "dv",
"method": "cname",
"status": "pending_deployment",
"settings": {
"min_tls_version": "1.2",
"http2": "on"
}
},
"custom_metadata": {
"key1": "value1",
"key2": "value2"
},
"custom_origin_server": "0001.blog.com"
}
}

​​ Issuance failed

{
"metadata": {
"event": {
"id": "<<WEBHOOK_ID>",
"type": "ssl.custom_hostname_certificate.issuance.failed",
"created_at": "2022-02-09T00:03:28.385080Z"
},
"account": {
"id": "<<ACCOUNT_ID>"
},
"zone": {
"id": "<<ZONE_ID>"
}
},
"data": {
"id": "<<CUSTOM_HOSTNAME_ID>",
"hostname": "blog.com",
"ssl": {
"id": "<<CERTIFICATE_ID>",
"type": "dv",
"method": "cname",
"status": "pending_issuance",
"cname": "_ca3-64ce913ebfe74edeb2e8813e3928e359.app.example2.com",
"cname_target": "dcv.digicert.com",
"validation_errors": [
{
"message": "caa_error: blog.example.com"
}
],
"settings": {
"min_tls_version": "1.2",
"http2": "on"
}
},
"custom_metadata": {
"key1": "value1",
"key2": "value2"
},
"custom_origin_server": "0001.blog.com"
}
}

​​ Certificate deployment

Once issued, certificates are deployed to Cloudflare’s global edge network.

​​ Deployment succeeded

{
"metadata": {
"event": {
"id": "<<WEBHOOK_ID>",
"type": "ssl.custom_hostname_certificate.deployment.succeeded",
"created_at": "2022-02-09T00:03:28.385080Z"
},
"account": {
"id": "<<ACCOUNT_ID>"
},
"zone": {
"id": "<<ZONE_ID>"
}
},
"data": {
"id": "<<CUSTOM_HOSTNAME_ID>",
"hostname": "blog.com",
"ssl": {
"id": "<<CERTIFICATE_ID>",
"type": "dv",
"method": "cname",
"status": "active",
"settings": {
"min_tls_version": "1.2",
"http2": "on"
}
},
"custom_metadata": {
"key1": "value1",
"key2": "value2"
},
"custom_origin_server": "0001.blog.com"
}
}

​​ Deployment failed

{
"metadata": {
"event": {
"id": "<<WEBHOOK_ID>",
"type": "ssl.custom_hostname_certificate.deployment.failed",
"created_at": "2022-02-09T00:03:28.385080Z"
},
"account": {
"id": "<<ACCOUNT_ID>"
},
"zone": {
"id": "<<ZONE_ID>"
}
},
"data": {
"id": "<<CUSTOM_HOSTNAME_ID>",
"hostname": "blog.com",
"ssl": {
"id": "<<CERTIFICATE_ID>",
"type": "dv",
"method": "cname",
"status": "pending_deployment",
"settings": {
"min_tls_version": "1.2",
"http2": "on"
}
},
"custom_metadata": {
"key1": "value1",
"key2": "value2"
},
"custom_origin_server": "0001.blog.com"
}
}

​​ Certificate deletion

​​ Deletion succeeded

{
"metadata": {
"event": {
"id": "<<WEBHOOK_ID>",
"type": "ssl.custom_hostname_certificate.deletion.succeeded",
"created_at": "2022-02-09T00:03:28.385080Z"
},
"account": {
"id": "<<ACCOUNT_ID>"
},
"zone": {
"id": "<<ZONE_ID>"
}
},
"data": {
"id": "<<CUSTOM_HOSTNAME_ID>",
"hostname": "blog.com",
"ssl": {
"id": "<<CERTIFICATE_ID>",
"type": "dv",
"method": "cname",
"status": "deleted"
},
"custom_metadata": {
"key1": "value1",
"key2": "value2"
},
"custom_origin_server": "0001.blog.com"
}
}

​​ Deletion failed

{
"metadata": {
"event": {
"id": "<<WEBHOOK_ID>",
"type": "ssl.custom_hostname_certificate.deletion.failed",
"created_at": "2022-02-09T00:03:28.385080Z"
},
"account": {
"id": "<<ACCOUNT_ID>"
},
"zone": {
"id": "<<ZONE_ID>"
}
},
"data": {
"id": "<<CUSTOM_HOSTNAME_ID>",
"hostname": "blog.com",
"ssl": {
"id": "<<CERTIFICATE_ID>",
"type": "dv",
"method": "cname",
"status": "pending_deletion"
},
"custom_metadata": {
"key1": "value1",
"key2": "value2"
},
"custom_origin_server": "0001.blog.com"
}
}

​​ Certificate renewal

Once issued, certificates are valid for a period of time depending on the certificate authority.

The actions that you need to perform to renew certificates depend on your validation method.

​​ Upcoming renewal

{
"metadata": {
"event": {
"id": "<<WEBHOOK_ID>",
"type": "ssl.custom_hostname_certificate.renewal.upcoming_certificate_expiration_notification",
"created_at": "2022-02-09T00:03:28.385080Z"
},
"account": {
"id": "<<ACCOUNT_ID>"
},
"zone": {
"id": "<<ZONE_ID>"
}
},
"data": {
"id": "<<CUSTOM_HOSTNAME_ID>",
"hostname": "blog.com",
"ssl": {
"id": "<<CERTIFICATE_ID>",
"status": "active",
"hosts": ["blog.example.com"],
"issuer": "DigiCertInc",
"serial_number": "1001172778337169491",
"signature": "ECDSAWithSHA256",
"uploaded_on": "2021-11-17T04:33:54.561747Z",
"expires_on": "2022-11-21T12:00:00Z",
"custom_csr_id": "7b163417-1d2b-4c84-a38a-2fb7a0cd7752",
"settings": {
"min_tls_version": "1.2",
"http2": "on"
}
},
"custom_metadata": {
"key1": "value1",
"key2": "value2"
},
"custom_origin_server": "0001.blog.com"
}
}

​​ Renewal succeeded

{
"metadata": {
"event": {
"id": "<<WEBHOOK_ID>",
"type": "ssl.custom_hostname_certificate.renewal.succeeded",
"created_at": "2022-02-09T00:03:28.385080Z"
},
"account": {
"id": "<<ACCOUNT_ID>"
},
"zone": {
"id": "<<ZONE_ID>"
}
},
"data": {
"id": "<<CUSTOM_HOSTNAME_ID>",
"hostname": "blog.com",
"ssl": {
"id": "<<CERTIFICATE_ID>",
"type": "dv",
"method": "cname",
"status": "pending_deployment",
"settings": {
"min_tls_version": "1.2",
"http2": "on"
}
},
"custom_metadata": {
"key1": "value1",
"key2": "value2"
},
"custom_origin_server": "0001.blog.com"
}
}

​​ Renewal failed

{
"metadata": {
"event": {
"id": "<<WEBHOOK_ID>",
"type": "ssl.custom_hostname_certificate.renewal.failed",
"created_at": "2022-02-09T00:03:28.385080Z"
},
"account": {
"id": "<<ACCOUNT_ID>"
},
"zone": {
"id": "<<ZONE_ID>"
}
},
"data": {
"id": "<<CUSTOM_HOSTNAME_ID>",
"hostname": "blog.com",
"ssl": {
"id": "<<CERTIFICATE_ID>",
"type": "dv",
"method": "cname",
"status": "pending_issuance",
"cname": "_ca3-64ce913ebfe74edeb2e8813e3928e359.app.example2.com",
"cname_target": "dcv.digicert.com",
"validation_errors": [
{
"message": "caa_error: blog.example.com"
}
],
"settings": {
"min_tls_version": "1.2",
"http2": "on"
}
},
"custom_metadata": {
"key1": "value1",
"key2": "value2"
},
"custom_origin_server": "0001.blog.com"
}
}

​​ Troubleshooting

Occasionally, you may see webhook notifications that do not include a corresponding <<CUSTOM_HOSTNAME_ID>> and hostname values.

This behavior is because each custom hostname can only have one certificate attached to it. Previously attached certificates can still emit webhook events but will not include the associated hostname and ID values.