> ## Documentation Index
> Fetch the complete documentation index at: https://developers.entri.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Secure Events

> Secure webhook events (domain.secure.provisioned, domain.secure.deprovisioned, domain.secure.certificate_renewal_failed) and the secure_status field.

This page documents the webhook events and payload fields relevant to Entri Secure. For the payload envelope and signature verification, see [Webhooks Overview](/webhooks-overview).

## Webhook event types

Entri Secure sends its own webhook events, in addition to the Secure fields it adds to the standard flow payload described below.

* [`domain.secure.provisioned`](#domain-secure-provisioned): A certificate was issued for the domain.
* [`domain.secure.deprovisioned`](#domain-secure-deprovisioned): Secure was removed from the domain.
* [`domain.secure.certificate_renewal_failed`](#domain-secure-certificate_renewal_failed): A certificate could not be renewed.

<Note>
  These events are only delivered if they are selected for your application in the Dashboard, under **Application → Webhooks**, in the **Webhook events** section. See [Choosing which events you receive](/webhooks-overview#choosing-which-events-you-receive).
</Note>

### `domain.secure.provisioned`

Sent when a security certificate is successfully issued for a domain and it's ready to serve visitors safely. Use it to confirm the domain is protected and let your user know everything is in place. It tells you which domain was secured and when it happened.

| Field | Type | Description |
| - | - | - |
| `id` | string | Entri's ID for the webhook event. |
| `user_id` | string | The user ID your application sent during setup, if any. |
| `domain` | string | The domain that was secured. |
| `type` | string | `"domain.secure.provisioned"`. |
| `application_url` | string | The application URL the domain points to, or `"exempt"` when it does not apply. |
| `redirect_to` | string | The destination the domain redirects to, or `"exempt"` when the domain is not a redirect. |
| `cname_target` | string | The CNAME target used for the DNS configuration. |
| `provisioned_at` | string (ISO 8601) | When the certificate was issued. |
| `provisioned_by` | \[api, modal] | How it was set up: `"api"` through the Secure API, `"modal"` through the Entri modal. |
| `secure_status` | \[active, inactive] | The domain's Secure status. `"active"` for this event. |

```json theme={"system"}
{
  "id": "9c128fe4-63cd-4ec4-9ae8-8a9d06c0e6de",
  "user_id": "your-provided-user-id",
  "domain": "shop.example.com",
  "type": "domain.secure.provisioned",
  "application_url": "www.mysaasapp.com",
  "redirect_to": "exempt",
  "cname_target": "my.saascompany.com",
  "provisioned_at": "2026-07-14T18:22:00.123456",
  "provisioned_by": "api",
  "secure_status": "active"
}
```

### `domain.secure.deprovisioned`

Sent when Secure is removed from a domain and Entri stops managing its certificate. Use it to close things out on your side or let the affected user know their domain is no longer covered. It tells you which domain was removed and when it happened.

| Field | Type | Description |
| - | - | - |
| `id` | string | Entri's ID for the webhook event. |
| `user_id` | string | The user ID your application sent during setup, if any. |
| `domain` | string | The domain Secure was removed from. |
| `type` | string | `"domain.secure.deprovisioned"`. |
| `application_url` | string | The application URL the domain pointed to, or `"exempt"` when it does not apply. |
| `redirect_to` | string | The destination the domain redirected to, or `"exempt"` when the domain was not a redirect. |
| `cname_target` | string | The CNAME target that was used for the DNS configuration. |
| `deprovisioned_at` | string (ISO 8601) | When Secure was removed. |
| `deprovisioned_by` | string | How it was removed. Currently always `"api"`. |
| `secure_status` | \[active, inactive] | The domain's Secure status. `"inactive"` for this event. |

```json theme={"system"}
{
  "id": "9c128fe4-63cd-4ec4-9ae8-8a9d06c0e6de",
  "user_id": "your-provided-user-id",
  "domain": "shop.example.com",
  "type": "domain.secure.deprovisioned",
  "application_url": "www.mysaasapp.com",
  "redirect_to": "exempt",
  "cname_target": "my.saascompany.com",
  "deprovisioned_at": "2026-08-20T11:47:31.221100",
  "deprovisioned_by": "api",
  "secure_status": "inactive"
}
```

### `domain.secure.certificate_renewal_failed`

Sent when a certificate managed by Secure can't be renewed because the domain's settings are missing something or pointing to the wrong place. Use it to alert the domain owner early, before their certificate lapses and visitors run into security warnings. It tells you which domain is affected, when the renewal failed, what the settings should look like, and what they currently look like, so the owner knows exactly what to fix.

| Field | Type | Description |
| - | - | - |
| `id` | string | Entri's ID for the webhook event. |
| `user_id` | string | The user ID your application sent during setup, if any. |
| `domain` | string | The domain whose renewal failed. |
| `type` | string | `"domain.secure.certificate_renewal_failed"`. |
| `application_url` | string | The application URL the domain points to, or `"exempt"` when it does not apply. |
| `redirect_to` | string | The destination the domain redirects to, or `"exempt"` when the domain is not a redirect. |
| `cname_target` | string | The CNAME target used for the DNS configuration. |
| `renewal_failed_at` | string (ISO 8601) | When the renewal failed. |
| `expected_records` | array of DNSRecord objects | The records the domain needs for Secure to renew the certificate. |
| `records_present` | array of DNSRecord objects | The records currently found for the domain. Empty if none could be read. |

<Note>
  For a domain set up on a root domain, `expected_records` contains the `A` records Secure expects. For any other domain it contains a single `CNAME` record pointing at your `cname_target`.
</Note>

```json theme={"system"}
{
  "id": "9c128fe4-63cd-4ec4-9ae8-8a9d06c0e6de",
  "user_id": "your-provided-user-id",
  "domain": "shop.example.com",
  "type": "domain.secure.certificate_renewal_failed",
  "application_url": "www.mysaasapp.com",
  "redirect_to": "exempt",
  "cname_target": "my.saascompany.com",
  "renewal_failed_at": "2026-09-01T03:15:09.554321",
  "expected_records": [
    { "host": "shop.example.com", "type": "CNAME", "value": "my.saascompany.com" }
  ],
  "records_present": [
    { "host": "shop.example.com", "type": "CNAME", "value": "old-target.example.net" }
  ]
}
```

## Status fields

* **`secure_status`**: Only relevant when using Entri Secure. Describes the status of SSL security configuration. Possible values:
  * `"pending"`: SSL configuration is pending.
  * `"success"`: SSL setup was successful.
  * `"failed"`: SSL setup failed.
  * `"exempt"`: Entri Secure does not apply to the current flow.

<Note>
  In the `domain.secure.*` events listed above, `secure_status` reports whether Secure is currently running on the domain and uses a different set of values: `"active"` or `"inactive"`. The values above apply to the standard flow payload.
</Note>

## Payload fields

* **`cname_target`**: Only applicable for Entri Power and Secure setups. The CNAME target used for DNS configuration (e.g. `"my.saascompany.com"`).