Skip to main content

CertCentral webhooks

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

CertCentral webhooks send you automatic updates when your certificates are issued. Use webhooks to trigger automated workflows when certificates are ready 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 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:

  • event (string): Event type.

  • data (object): Object with event data.

Certificate issuance events

CertCentral sends a webhook event each time 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 issuance events have this format:

{
  "event": "certificate_issued",
  "data": {
    "order_id": 12345,
    "certificate_id": 23456
  }
}

Name

Type

Description

event

string

For certificate issuance events, the type is certificate_issued.

data

object

Object with event data.

.. order_id

number

ID of the order associated with the certificate.

.. certificate_id

number

ID of the issued certificate.

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 status codes (2XX).

Create a webhook

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

  1. In your CertCentral account, in the sidebar menu, select Settings > Webhooks.

  2. On the webhooks page, enter your endpoint in the Enter your endpoint URL field. Make sure to include the https:// prefix.

  3. 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"
    }
  4. 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.

  5. 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.

  1. In your CertCentral account, in the sidebar menu, select Settings > Webhooks.

  2. On the webhooks page, select Deactivate push notification.

  3. 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.

  1. In your CertCentral account, in the sidebar menu, select Settings > Webhooks.

  2. On the webhooks page, select Update URL.

  3. Follow steps 2-4 from Create a webhook to enter, test, and verify the new endpoint.

Troubleshoot endpoint URL

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

  1. Make sure your webhook listener is running.

  2. Check firewall ports, ensure 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.

  3. Check DNS resolution of the domain where the webhook listener is hosted.

  4. Send a message to the endpoint where your webhook is hosted with curl command or Postman to make sure your service is active and receiving POST requests.

  5. 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.

  6. Check latency. If DigiCert does receive an HTTP 2xx within 10 seconds, 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.