Webhooks will only be delivered to accounts set as Admin
or Developer
roles within the Dashboard.
Entri uses webhooks to notify your backend about the status of a domain that has been connected or sold. You can configure a URL in the Entri dashboard to receive these webhook events.
When a domain has been added by a user, Entri sends the following webhook payload:
The webhook payload includes several fields with nested objects, depending on the type of event. Below is a complete description of each key and value.
id
: A unique identifier for the webhook event (e.g. "1234567890-abcdefg-1234567890"
).user_id
: The ID of the user who initiated the domain-related action (e.g. "your-provided-user-id"
).domain
: The domain involved in the event (e.g. "example.com"
).subdomain
: The subdomain associated with the event, if any (e.g. "shop"
).type
: Defines the type of event. Possible values:
"domain.added"
: Indicates that DNS records have been successfully added.
"domain.purchased"
: Indicates that the domain order creation has been completed."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."purchase.error"
: Indicates an error during the domain purchase process."purchase.confirmation.expired"
: The purchase confirmation has expired (abandoned flow).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.This field is present in the webhook when using the DMARC Handling: Advanced 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).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.power_status
: Only relevant when using Entri Power. Describes the status of the advanced features configuration. Possible values:
"pending"
: Setup of advanced features is pending."success"
: Advanced features setup was successful."failed"
: Setup of advanced features failed."exempt"
: Entri Power does not apply to the current flow.monitor_status
: Only relevant when using Entri Monitor. Describes the status of the monitoring feature. This key will not be shown on flows that don’t use Entri Monitor. Possible values:
"pending"
: Monitoring domain setup is pending."success"
: Monitoring domain setup was successful."failed"
: Monitoring domain setup failed.cname_target
: Only applicable for Entri Power and Secure setups. The CNAME target used for DNS configuration (e.g. "my.saascompany.com"
).
purchased_domains
: An array of domains that were purchased during the transaction. This field is only relevant for Entri Sell. Example:
free_domain
: Indicates whether the domain was obtained through a free domain flow. Possible values:
true
: The domain was free.false
: The domain was not free.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:
records_non_propagated
: An array of DNS records that have not yet propagated. The structure is the same as records_propagated
.
"type": "domain.added"
: An event type indicating that a domain has been added."propagation_status": "pending"
: DNS record propagation is still in progress."secure_status": "success"
: SSL configuration completed successfully."power_status": "failed"
: The advanced feature configuration process has failed."cname_target": "my.saascompany.com"
: The CNAME target for Entri Power or Secure configuration.If any part of the webhook object is updated, subsequent webhooks will include ALL fields. Example update:
If the DNS records are not fully propagated on the first attempt, Entri will retry at increasing intervals (1 minute, 2 minutes, 4 minutes, etc.). This process will continue for up to 72 hours. After 72 hours, if the records are still not propagated, a webhook with "type": "domain.timeout"
will be sent.
The dkim_status
field is set to exempt
if:
Enable support for DKIM
setting is disabled for your applicationId
.This documentation describes how to verify Entri webhook signatures using the payload ID signature method (recommended).
When Entri sends a webhook, it:
Id
valueEntri-Signature
headerId
valueEntri-Signature
header from the webhook request