> ## 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.
# Connect Events
> Browser events (onSuccess, onEntriClose, onEntriStepChange, onSharedFlowSent, onEntriManualSetupDocumentationClick, onEntriRequestClose) and Connect-scoped webhook events.
This page documents the webhook events and payload fields relevant to Entri Connect. For the payload envelope and signature verification, see [Webhooks Overview](/webhooks-overview).
## Webhook event types
* `"domain.added"`: Indicates that DNS records have been successfully added.
* For **Entri Sell**, this means the domain has been registered and connected.
* For **Entri Connect**, it confirms that DNS records have been added to an existing domain.
* Multiple messages of this type may be received for the same domain. This occurs when either the propagation\_status or redirection\_status changes.
* `"domain.propagation.timeout"`: This event is very rare and is triggered if DNS records fail to propagate after 72 hours. It is highly uncommon for domains connected through the automatic flow.
* `"domain.flow.completed"`: Indicates that the user has completed the Entri domain connection flow. This event does not convey any propagation status — it only confirms that the user finished the flow steps.
## Status fields
* **`propagation_status`**: The status of DNS record propagation. Possible values:
* `"pending"`: DNS records are still being propagated.
* `"success"`: DNS records have been successfully propagated.
* `"failed"`: DNS record propagation has failed. This is triggered if the records are not propagated even after 72 hours.
* `"exempt"`: Only present in notifications with `type:"purchase.confirmation.expired"`.
* **`dkim_status`**: The status of DKIM (DomainKeys Identified Mail) configuration. Possible values:
* `"pending"`: DKIM setup is pending.
* `"success"`: DKIM configuration has been successfully completed.
* `"failed"`: DKIM setup failed.
* `"exempt"`: DKIM setup is exempt, usually if the user does not use a supported email provider (e.g. Google or Microsoft).
* **`redirection_status`**: The status of domain redirection. Possible values:
* `"pending"`: Redirection setup is in progress.
* `"success"`: Redirection setup has completed successfully.
* `"failed"`: Redirection setup failed.
* `"exempt"`: Redirection is exempt from this setup.
* **`setup_type`**: Indicates whether the setup was done automatically or manually. Possible values:
* `"automatic"`: Setup was performed automatically.
* `"manual"`: Setup required manual intervention.
* `"async"`: Setup was done using the [DNS asynchronous update](/sell/sdk#asynchronous-dns-configurations-entri-sell-only).
* `"api"`: The setup was performed using the **Entri Sell Enterprise API**
### Advanced DMARC configuration feature
This field is present in the webhook when using the [DMARC Handling: Advanced Options](/advanced-dmarc-options) or `validateDmarc` features.
* **`dmarc_updated`**: Reflects the status of DMARC (Domain-based Message Authentication, Reporting, and Conformance) updates. Possible values:
* `"true"`: DMARC settings have been updated.
* `"false"`: DMARC settings were not updated.
* `"exempt"`: DMARC is not applicable in this situation (e.g. for domains that don’t require it).
## Data object (DNS records)
The `data` object contains the DNS records that have been propagated and those that are pending.
* **`records_propagated`**: An array of DNS records that have been successfully propagated. Each record contains:
* **`type`**: The type of DNS record (e.g. `"A"`, `"CNAME"`).
* **`host`**: The hostname for which the DNS record applies (e.g. `"smallbusiness.com"`).
* **`value`**: The value of the DNS record (e.g. `"54.153.2.220"`).
* **`applicationUrl`**: (optional, Entri Power only) The application URL tied to the propagated DNS record (e.g. `"www.example.com"`).
* **`powerRootPathAccess`**: (optional, Entri Power only) An array of paths accessible through Entri Power. Example:
```json theme={null}
["path1", "path2", "pathN"]
```
* **`records_non_propagated`**: An array of DNS records that have not yet propagated. The structure is the same as `records_propagated`.
## Shared flows
When a flow is initiated via a sharing link or with a `sharedFlowId`, webhook events include an `origin_flow_id` to correlate the derived flow back to the origin. See [Shared Links](/connect/shared-links#correlating-shared--derived-flows) for details.
## Frontend event: onSharedFlowSent
When using shared flows in the frontend experience, Entri exposes an `onSharedFlowSent` callback that fires when a user copies a shared flow and reaches the shared-flow congratulations screen.
This event includes the `sharedFlowId`, allowing you to bind:
* the **sharedFlowId** (originating / shared flow)
* the **derived flow run** that completes later (via `origin_flow_id` in webhooks)
Example usage:
```js theme={null}
entri.purchaseDomain({
// ...
onSharedFlowSent: ({ sharedFlowId }) => {
// Persist sharedFlowId to correlate with webhook origin_flow_id
}
})
```
## Browser callback events
The following events are useful for following up the user's navigation and take action under certain circumstances, for example, leading the user to your manual setup guide in case you don't want to use Entri's.
### `onSuccess` Callback Event
This event is triggered when the user reaches the **Congratulations** screen in Entri Connect and Entri Sell, regardless of whether the setup was **automatic** or **manual**. Use this event to capture a definitive success signal and the `jobId` that identifies the flow.
#### Sample usage:
```JavaScript JavaScript theme={null}
function handleOnSuccess(event) {
console.log('onSuccess', event.detail);
}
window.addEventListener('onSuccess', handleOnSuccess, false);
```
#### Sample `event.detail` object response:
```JSON JSON theme={null}
{
"domain": "example.com",
"success": true,
"setupType": "automatic",
"provider": "Provider name",
"freeDomain": true,
"jobId": "2132b20f-e522-42fc-9604-5a53b1f13a4b"
}
```
#### Event details object description
| Name | Type | Description |
| ---------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| domain | string | Domain that was configured. |
| success | boolean | Always `true` for this event, indicating the flow completed successfully. |
| setupType | string | Type of DNS setup used: `automatic` or `manual`. |
| provider | string | DNS provider used to configure the domain, or `unknown` if not detected. |
| freeDomain | boolean | Only included for Entri Sell **free domain** flows; otherwise may be omitted. |
| jobId | string (UUID) | The unique identifier for the Connect/Sell flow. It is returned by the **initialize** response and is also included in all related webhooks. |
The `onSuccess` event complements existing browser events and is the recommended source to capture the `jobId` for subsequent server-side operations (e.g., retrieving the last webhook or triggering a propagation re-check).
### `onEntriClose` Callback Event
This event gets triggered as soon as the modal is closed, giving you back useful information about the latest status of the flow.
#### Sample usage:
```JavaScript JavaScript theme={null}
function handleOnEntriClose(event) {
console.log('onEntriClose', event.detail);
}
window.addEventListener('onEntriClose', handleOnEntriClose, false);
```
#### Sample `event.detail` object response:
```JSON JSON theme={null}
{
"domain": "example.com",
"success": true,
"setupType": "automatic",
"provider": "Provider name",
"lastStatus": "IN_PROGRESS",
"freeDomain": true, // Only applies to Entri Sell free domain flows
"error": { // Added to the event details if the user closed the app after an error screen.
"code": "ProviderError",
"title": "Social Login Not Supported",
"details": "You are trying to login with Social Account, please try logging in from [PROVIDER_NAME] Account"
}
}
```
#### Event details object description
| Name | Type | Description |
| -------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| domain | string | Domain that the user entered. Can be null if the user exits before entering a domain. |
| success | boolean | Was the setup of the domain completed? |
| setupType | string | Type of DNS setup. Can be "automatic", `manual`, `sharedLogin`, `purchase` or `null` if the user didn't reach the set up stage. Additionally, semiautomatic may be returned if the user selected a provider manually that supports automatic set up. |
| provider | string | Provider name used to configure the domain or "unknown" if it was not detected. |
| lastStatus | string | lastStatus can be used if you want more information about where the user dropped off. Find all possible values below. |
| manualScreenDisabled | boolean | Determines if the modal was closed because the flow reached the Manual Screen and it was disabled using the whiteLabel.customProperties.manualConfiguration.disableScreen property. |
| freeDomain | boolean | Determines if the flow was for an Entri Sell free domain flow. Not included on other types of flow. |
| error | object | Added to the event details if the user closed the app after an error screen. |
| error.code | string | Exit error code |
| error.title | string | Error title shown to the end user on the error screen |
| error.details | string | Error details shown to the end user on the error screen |
Errors description available at the [Possible error codes](#possible-error-codes) section.
#### `lastStatus` possible values
| lastStatus | Description |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| INITIAL | Initial screen for Entri Connect, Secure and Power. |
| ENTER\_DOMAIN | Enter your domain screen in case there's no prefilledDomain |
| DOMAIN\_ANALYSIS | The domain is under the DNS analysis |
| DOMAIN\_SETUP | The domain is on the DNS configuration step |
| IN\_PROGRESS | The user exited the Entri modal while the DNS setup was in progress. |
| EXISTING\_RECORDS | The user exited the Entri modal when prompted if they want to override an existing set of DNS records. |
| LOGIN | The user exited the Entri modal flow during the login process (when prompted for their login credentials) |
| LOGIN\_2FA | The user exited the Entri modal flow during the login process (when prompted for 2FA verification) |
| MANUAL\_CONFIGURATION | The user exited the Entri modal after manual DNS configuration instructions were presented. |
| PROVIDER\_MANUAL\_SELECTION | The user entered the providers' list for manual selection |
| EXIT\_WITH\_ERROR | The user exited the Entri modal after an error occurred. |
| DKIM\_SETUP | The user exited the Entri modal after prompting |
| FINISHED\_SUCCESSFULLY | The user has successfully configured their domain using the automatic flow. |
| FINISHED\_SUCCESSFULLY\_MANUAL | The user has successfully configured their domain using the manual flow. |
| FINISHED\_SUCCESSFULLY\_LINK\_SHARED | The user completed the flow by sharing a configuration link (shared‑flow experience) rather than configuring the DNS themselves. |
### `onEntriManualSetupDocumentationClick` Event
This event is triggered when the user has clicked on the "Follow our step-by-step guide" link on the Manual configuration screen. It doesn't include any additional information within the `event.detail` object. This is useful for triggering proprietary javavascript based solutions when the user needs help with configuring the manual flow, e.g. opening support chats, etc.
#### Sample usage:
```JavaScript JavaScript theme={null}
function myCustomFunction(event) {
//Custom code here e.g. open chat app
}
window.addEventListener('onEntriManualSetupDocumentationClick', myCustomFunction, false);
```
### `onEntriStepChange` Event
This event is triggered each time a different screen is shown within the Entri configuration process. It serves the purpose of offering additional user journey insights, making it useful for implementing listeners and triggering third-party tracking system events when necessary.
#### Sample usage:
```JavaScript JavaScript theme={null}
function myCustomFunction(event) {
console.log('onEntriStepChange', event.detail);
}
window.addEventListener('onEntriStepChange', myCustomFunction, false);
```
#### Sample `event.detail` object response:
```JSON JSON theme={null}
{
"domain": "example.com",
"provider": "Provider name",
"step": "ENTER_DOMAIN",
"user": "user-123456",
"error": { // Added to the event details if the user closed the app after an error screen.
"code": "ProviderError",
"title": "Social Login Not Supported",
"details": "You are trying to login with Social Account, please try logging in from [PROVIDER_NAME] Account"
}
}
```
#### Event details object description
| Name | Type | Description |
| ------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| domain | string | Domain that the user entered. Can be null if the user exits before entering a domain. |
| provider | string | Provider name used to configure the domain or "unknown" if it was not detected. |
| step | boolean | The current step the user is visualizing |
| user | string | The userId sent over the initial configuration. Helpful for mapping users vs. flows. |
| error | object | Added to the event details if the user closed the app after an error screen. |
| error.code | string | Exit error code |
| error.title | string | Error title shown to the end user on the error screen |
| error.details | string | Error details shown to the end user on the error screen |
| pendingDomains | array | (Multi-domain flows) Domains that still need to be configured after the current step. |
| processedDomains | array | (Multi-domain flows) Domains that have already been processed (successfully or with error) in the current flow. |
| conditionalRecords | array | DNS records that apply only conditionally for the current step — for example, records that depend on the selected provider or on the user's chosen subdomain. Each entry follows the same shape as `dnsRecords`. |
Errors description available at the [Possible error codes](#possible-error-codes) section.
#### `step` possible values
| lastStatus | Description |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| INITIAL | Initial screen for Entri Connect, Secure and Power. |
| ENTER\_DOMAIN | Enter your domain screen in case there's no prefilledDomain |
| DOMAIN\_ANALYSIS | The domain is under the DNS analysis |
| DOMAIN\_SETUP | The domain is on the DNS configuration step |
| IN\_PROGRESS | The user exited the Entri modal while the DNS setup was in progress. |
| EXISTING\_RECORDS | The user exited the Entri modal when prompted if they want to override an existing set of DNS records. |
| LOGIN | The user exited the Entri modal flow during the login process (when prompted for their login credentials) |
| LOGIN\_2FA | The user exited the Entri modal flow during the login process (when prompted for 2FA verification) |
| MANUAL\_CONFIGURATION | The user exited the Entri modal after manual DNS configuration instructions were presented. |
| PROVIDER\_MANUAL\_SELECTION | The user entered the providers' list for manual selection |
| EXIT\_WITH\_ERROR | The user exited the Entri modal after an error occurred. |
| DKIM\_SETUP | The user exited the Entri modal after prompting |
| FINISHED\_SUCCESSFULLY | The user has successfully configured their domain using the automatic flow. |
| FINISHED\_SUCCESSFULLY\_MANUAL | The user has successfully configured their domain using the manual flow. |
| FINISHED\_SUCCESSFULLY\_LINK\_SHARED | The user completed the flow by sharing a configuration link (shared‑flow experience) rather than configuring the DNS themselves. |
### `onEntriRequestClose` Event
This event lets host applications run their own confirmation UI (or cleanup logic) when the user clicks the close (X) button, instead of Entri's built‑in "Are you sure you want to leave?" dialog.
This event is **gated** by [`whiteLabel.customProperties.general.useCustomExitConfirmation`](/connect/white-label#whitelabel-customproperties-object). Set it to `true` to enable the event; otherwise Entri shows its own default exit confirmation dialog and this event does **not** fire.
When the event fires, Entri **does not** close the modal automatically. After your own confirmation UI resolves, your app is responsible for calling [`entri.close()`](/connect/sdk#entri-close) to dismiss the widget. The regular `onEntriClose` event then fires through the normal close flow.
#### Sample usage:
```JavaScript JavaScript theme={null}
function handleRequestClose(event) {
console.log('onEntriRequestClose', event.detail);
// Show your own confirmation UI here.
// If the user confirms exit, call entri.close():
// entri.close();
}
window.addEventListener('onEntriRequestClose', handleRequestClose, false);
```
#### `event.detail` payload
| Field | Type | Always present | Description |
| ------------------ | --------- | ----------------- | --------------------------------------------------------------------------------------------------------- |
| `step` | string | Yes | The current `EntriStatus` at the time the user requested to close. See the status table above. |
| `pendingDomains` | string\[] | Multi-domain only | Domains still pending setup. Only included when the flow is configured for multiple domains. |
| `processedDomains` | string\[] | Multi-domain only | Domains that have already been processed. Only included when the flow is configured for multiple domains. |
### Possible `error` codes
Below is a list of potential Entri modal errors. As a note, this list may not be exhaustive as some will be errors directly from the provider.
| Error message | Title | Description |
| -------------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| AccessDeniedError | Invalid Permissions | We’re sorry an error occurred when trying to set up your domain. Please try again. |
| AuthCodeError | 2FA code invalid. | Invalid code |
| EmailNotVerifiedError | Unverified email | You need to complete the email verification process in your provider account. |
| InvalidCredentialsError | You’ve exceeded the maximum number of login attempts | Please reset your password or set up your domain manually. |
| InvalidDomainError | Domain not found | We found the domain in your `{provider}` account. However, your nameservers are pointed elsewhere. This means `{provider}` does not manage your DNS. Please try again with the service that manages your DNS settings. |
| InvalidNameservers | Domain not found | We couldn’t find the domain you entered in your provider account. |
| GenericError | An error occurred when trying to set up your domain | We’re sorry an error occurred when trying to set up your domain. Please try again. |
| PurchaseDomainError | An error occurred when trying to set up your purchase. | Please refresh the page and try again. |
| RegistroDomainInTransition | Domain in transition | Registro.br is transitioning your account to advanced DNS mode. This can take up to 5 minutes. Please try again in 5 minutes. |
| SessionError | Session Error | Your session has timed out. Please refresh the page and try again. |
| SpfRecordsLimitError | An error occurred when trying to set up your domain | SPF record cannot have more than 10 domains |
| SpfRecordsLengthError | An error occurred when trying to set up your domain | SPF record cannot be longer than 255 characters |
| UserInputTimeoutError | Your session has timed out | For your security, your session has timed out. Please start over. |
| TimeoutError | An error occurred when trying to set up your domain | We're sorry, the process took more time than expected to complete. Please try again. |