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
Cloudflare sends this alert when certificates move from a status of pending_validation to pending_issuance.
{ "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
Cloudflare sends this alert each time a certificate remains in a pending_validation status during DCV retries.
{ "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
Cloudflare sends this alert when certificates move from a status of pending_validation or pending_issuance to pending_deployment.
{ "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
Cloudflare sends this alert each time a certificate remains in a status of pending_issuance during DCV retries.
{ "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
Cloudflare sends this alert when certificates move from a status of pending_deployment to active.
{ "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
Cloudflare sends this alert each time a certificate remains in a status of pending_deployment during DCV retries.
{ "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
Cloudflare sends this alert when certificates move from a status of pending_deletion to deleted.
{ "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
Cloudflare sends this alert each time a certificate remains in status of pending_deletion during DCV retries.
{ "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
Cloudflare sends this alert when certificates move from a status of active to pending_deployment.
{ "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
Cloudflare sends this alert when certificates move from a status of active to pending_issuance.
{ "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.