CertCentral webhooks

Use webhooks to receive push notifications when your certificates are issued or revoked.

CertCentral webhooks send you automatic updates when your certificates are issued or revoked. Use webhooks to trigger automated workflows without having to query the CertCentral Services API for your order status.

For example, when a webhook sends you a notification that a certificate is ready, you can send a callback API request to download the certificate, or you can programmatically alert the certificate owner.

Note

Only CertCentral admins can create webhooks. Webhooks are a beta feature and may not be enabled for your account.

Webhook endpoint requirements

To receive webhook events, you must host a webhook listener at an endpoint URL you control. You use this endpoint to subscribe to webhook events in your CertCentral account.

How you choose to create and maintain your webhook listener is beyond the scope of this documentation. DigiCert’s only requirements are that your endpoint must:

Use HTTPS.
Be public-facing. For additional security, we recommend you configure the allowlist for your webhook listener to only accept incoming requests from DigiCert services in this IP address range: 216.168.240.0/20. Learn more about the expanded range of IP addresses for DigiCert services.
Respond to POST requests with standard successful HTTP response status codes (2XX).

Webhook events

An update from a CertCentral webhook is called an event. CertCentral sends webhook events as JSON-formatted data objects to an endpoint URL you control.

Webhook events have these key-value pairs:

Name	Type	Description
event	string	Event type. Possible values: See Webhook event types.
data	object	Object with event data.
.. order_id	number	ID of the order associated with the event.
.. certificate_id	number	ID of the certificate associated with the event.

Webhook event types

Name	Description
certificate_issued	CertCentral sends a webhook event when DigiCert issues a certificate in your account. CertCentral sends certificate issuance events for all certificate types. CertCentral only sends certificate issuance events for certificates that aren’t immediately issued.
certificate_revoked	CertCentral sends a webhook event when a certificate in your account is revoked.

Examples

Authenticate webhook events

CertCentral supports the option to add a custom secret key to your webhooks. Use the secret key to verify the source of webhook events, ensuring their authenticity and enhancing the security of your webhook listener.

You can add a secret key when creating or updating a webhook. If a webhook has a secret key, webhook events include the secret key value in the custom request header X-WEBHOOK-KEY. To prevent your webhook listener from processing invalid events, configure your endpoint to validate the X-WEBHOOK-KEY value in each received event.

Create a webhook

After setting up a webhook listener at an endpoint you control, you can create a webhook in CertCentral.

In your CertCentral account, in the sidebar menu, select Settings > Webhooks.
On the webhooks page, enter your endpoint in the Enter your endpoint URL field. Make sure to include the https:// prefix.
Optional: For enhanced security, add a secret key to the webhook.
Under Do you have a secret key, select the relevant option:
- No
  Continue to step 4.
- Yes
  Enter your secret key value in the secret key field. The key must be at least 32 characters.
Under Receive updates on, check the box next to each event type you want to receive.
Test your endpoint. Select Send test notification to send a test event that verifies CertCentral can connect to your endpoint URL. Your endpoint should respond to the test event with an HTTP status code of 200 OK. The test event has this format:
```
{
  "event": "test_webhook_endpoint"
}
```
Complete a verification challenge to prove you have access to the data your webhook listener receives.
1. Select Send verification token to send an event with a challenge token to your endpoint. The challenge event has this format:
```
{
  "event": "challenge_webhook_endpoint",
  "data": {
    "token": <token>,
    "webhook_id": 12345
  }
}
```
2. Within 30 minutes of receiving the token, enter it on the webhook page in your CertCentral account. Then, select Activate webhook.
Your webhook is now active. CertCentral immediately begins sending events to your endpoint each time a certificate is issued in your account.

Deactivate webhook

To pause or stop receiving notifications, deactivate your webhook.

In your CertCentral account, in the sidebar menu, select Settings > Webhooks.
On the webhooks page, select Deactivate push notification.
Notifications are paused. To resume, select Activate push notification.

Update endpoint URL

If you change the endpoint where your webhook listener is hosted, you can update the endpoint URL for your webhook.

In your CertCentral account, in the sidebar menu, select Settings > Webhooks.
On the webhooks page, select Update URL.
Follow steps 2-4 from Create a webhook to enter, test, and verify the new endpoint.

Troubleshoot your webhook endpoint

If your webhook endpoint is not receiving notifications, follow these steps to try to identify the problem:

Make sure your webhook listener is running.
Check your firewall ports to make sure DigiCert’s IP address is allowed. If you use allowlists, make sure your webhook listener accepts incoming requests from DigiCert services in this IP address range: 216.168.240.0/20. Learn more about the expanded range of IP addresses for DigiCert services.
Check the DNS resolution of the domain where the webhook listener is hosted.
Use an HTTP client like cURL or Postman to send a POST request to your webhook endpoint to make sure your service is active and receiving requests.
Send a test notification to your webhook listener. In your CertCentral account, on the webhooks page, select Send test notification. Alternatively, use the Send test event API endpoint.
Check latency. If DigiCert doesn't receive a status response code of 2XX from your service within 10 seconds of sending an event, the request failed.

Webhook APIs

The CertCentral Services API exposes endpoints to create and manage webhooks in your CertCentral account. The reference documentation for webhook API endpoints is available at Services API – Webhooks.

In this section: