Create webhook

POST https://www.digicert.com/services/v2/webhook

Use this endpoint to create a webhook in your CertCentral account.

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

After you create a webhook:

Send a test event to ensure CertCentral can communicate with your webhook listener.
Complete a verification challenge to demonstrate you have access to data the endpoint receives. To complete the challenge using the API, use the Send challenge token and Verify challenge token API endpoints.
Activate the webhook to start receiving certificate issuance events.

For more information about webhooks in CertCentral, see CertCentral webhooks.

Usage and limitations

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 can only create one webhook in your CertCentral account. After creating a webhook, you can change the endpoint URL where you listen for webhook events by using the Update webhook endpoint API.

Example requests and responses

Example 1. cURL

curl --request POST 'https://www.digicert.com/services/v2/webhook' \
--header 'X-DC-DEVKEY: {{api_key}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "endpoint": "https://webhook.example.com/endpoint",
  "events": [
    "organization_revalidation_notice",
    "domain_expired",
    "domain_revalidation_notice",
    "certificate_revoked",
    "order_rejected",
    "organization_expired",
    "organization_validated",
    "domain_validated",
    "certificate_issued"
  ],
  "webhook_settings": {
    "instant_issue_webhook_notification": "1",
    "webhook_notification_frequency": [90,60,30,7,0,-7],
    "webhook_send_certificate_chain": "1",
    "webhook_send_instant_issued_certificate_chain": "1"
  }
}'

Request parameters

Name	Opt/Req	Type	Description
endpoint	required	string	Endpoint URL where your webhook listener is hosted. Must begin with https://. Learn more: Webhook endpoint requirements
secret	optional	string	Secret key value. Must be at least 32 characters. If provided, events DigiCert sends to your endpoint include an `X-WEBHOOK-KEY` request header. This request header contains your secret key value. For increased security, configure your webhook listener to validate the `X-WEBHOOK-KEY` value in each received event. If no `secret` is provided when creating the webhook, DigiCert omits the `X-WEBHOOK-KEY` request header from events sent to your webhook listener.
events	optional	array of strings	List of event types the webhook is subscribed to. If not provided, the webhook is subscribed to `certificate_issued` events. Allowed values: See CertCentral event types.
webhook_settings	optional	object	Optional settings for customizing certificate issued, validation expired, and revalidation notice events.
.. webhook_notification_frequency	optional	array of integers	Array of values that determine when you receive notifications for `organization_expired`, `organization_revalidation_notice`, `domain_expired`, and `domain_revalidation_notice` events. The `webhook_notification_frequency` array should include one or more of the following numbers (order doesn't matter): `90`: 90 days before event `60`: 60 days before event `30`: 30 days before event `7`: Seven days before event `0`: Day of event `-7`: Seven days after event
.. instant_issue_webhook_notification	optional	string	If `0`, CertCentral sends `certificate_issued` events only for certificates that are not issued the instant the order is created. If `1`, CertCentral sends `certificate_issued` events every time a certificate is issued, including certificates issued immediately.
.. webhook_send_certificate_chain	optional	string	If `1`, `certificate_issued` events for public and private TLS/SSL certificates include the certificate chain for certificates that are not not issued the instant the order is created. Otherwise, `0` (default). Learn more: Customize certificate issued events
.. webhook_send_instant_issued_certificate_chain	optional	string	If `1`, `certificate_issued` events for public and private TLS/SSL certificates include the certificate chain for certificates issued the instant the order is created. Otherwise, `0` (default). Learn more: Customize certificate issued events

Response parameters

Name	Type	Description
webhook_id	number	ID of the new webhook.

Error cases

Status	Code	Description
400	webhook_invalid_endpoint	The provided endpoint is not valid. Make sure the endpoint begins with https:// and try again.
400	webhook_configured_already	A webhook already exists in the CertCentral account. To change the endpoint URL where you listen for webhook events, use the Update webhook endpoint API.
400	webhook_endpoint_error	The provided endpoint is not responding or accepting requests. Make sure your webhook listener is configured correctly and try again. For more information, see Webhook endpoint requirements.

In this section: