CertCentral webhooks

Use webhooks to receive push notifications for events in your CertCentral account.

CertCentral webhooks send you automatic updates for certificate issuance and validation events. Use webhooks to trigger automated workflows without polling the CertCentral Services API for certificate and validation 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

Webhooks are not enabled for all CertCentral accounts. To request access to webhooks, contact your account manager or DigiCert Support.

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 IP address changes.
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. You decide what events to receive notifications for when you create or update your webhook.

CertCentral webhook events have these key/value pairs:

event (string): Event name.
data (object): Object with event data.

Different events return different information in the data object. To see the data for each event, see CertCentral event types.

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.

Note

Only CertCentral admins can create webhooks.

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.
Optional: Customize the settings for certificate issued, validation expired, and revalidation notice events. Learn more:
- Customize certificate issued events
- Customize validation expired and revalidation notice events
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 when an event is triggered 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.

Webhook event logs

In the webhook event log, CertCentral stores a history of all events sent to your webhook listener. Each entry in the event log has the following information:

Timestamp
Event type
HTTP response code returned by the webhook listener

To view webhook event logs:

In your CertCentral account, in the sidebar menu, select Settings > Webhooks.
On the webhooks page, select Webhook event logs.
(Optional) Use the Event and HTTP response code fields to filter the logs.

Tip

To access the webhook event log via API, use the Webhook event logs 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: