---
title: "Create webhook"
source_url: https://dev.digicert.com/certcentral-apis/services-api/webhooks/create-webhook.html
api_method: POST
api_endpoint: "/services/v2/webhook"
api_url: "https://www.digicert.com/services/v2/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:

1. [Send a test event](https://dev.digicert.com/md/certcentral-apis/services-api/webhooks/send-test-event.md) to ensure CertCentral can communicate with your webhook listener.
2. 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](https://dev.digicert.com/md/certcentral-apis/services-api/webhooks/send-challenge-token.md) and [Verify challenge token](https://dev.digicert.com/md/certcentral-apis/services-api/webhooks/verify-challenge-token.md) API endpoints.
3. [Activate the webhook](https://dev.digicert.com/md/certcentral-apis/services-api/webhooks/activate-webhook.md) to start receiving certificate issuance events.

For more information about webhooks in CertCentral, see [CertCentral webhooks](https://dev.digicert.com/md/certcentral-apis/webhooks.md).

## 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](https://dev.digicert.com/md/certcentral-apis/services-api/webhooks/update-webhook-endpoint.md) API.

## Example requests and responses

## cURL

```bash
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"
  }
}'
```

## 201 Created

```json
{
  "webhook_id": 1234
}
```

## Request parameters

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

## Response parameters

<table class="params-table">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>webhook_id</td>
<td>number</td>
<td>ID of the new webhook.</td>
</tr>
</tbody>
</table>

## Error cases

<table>
<thead>
<tr>
<th>Status</th>
<th>Code</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>400</td>
<td>webhook_invalid_endpoint</td>
<td>The provided endpoint is not valid. Make sure the endpoint begins with <em>https://</em> and try again.</td>
</tr>
<tr>
<td>400</td>
<td>webhook_configured_already</td>
<td>A webhook already exists in the CertCentral account. To change the endpoint URL where you listen for webhook events, use the <a href="https://dev.digicert.com/md/certcentral-apis/services-api/webhooks/update-webhook-endpoint.md">Update webhook endpoint</a> API.</td>
</tr>
<tr>
<td>400</td>
<td>webhook_endpoint_error</td>
<td>The provided endpoint is not responding or accepting requests. Make sure your webhook listener is configured correctly and try again. For more information, see <a href="https://dev.digicert.com/md/certcentral-apis/webhooks.md#section-idm4498246235270433287904676551">Webhook endpoint requirements</a>.</td>
</tr>
</tbody>
</table>