Available starting at the Premium Tier

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.

​
Example webhook payload

When a domain has been added by a user, Entri sends the following webhook payload:

{
  "id": "1234567890-abcdefg-1234567890",
  "user_id": "your-provided-user-id",
  "domain": "example.com",
  "subdomain": "shop",
  "type": "domain.added",
  "propagation_status": "pending",
  "dkim_status": "success",
  "redirection_status": "exempt",
  "setup_type": "automatic",
  "secure_status": "success",
  "power_status": "success",
  "dmarc_updated": "exempt",
  "cname_target": "my.saascompany.com",
  "purchased_domains": ["domain1.com", "domain2.com", "domainN.com"],
  "free_domain": true,
  "data": {
    "records_propagated": [
      {
        "type": "A",
        "host": "smallbusiness.com",
        "value": "54.153.2.220",
        "applicationUrl": "www.example.com",
        "powerRootPathAccess": ["path1", "path2", "pathN"]
      },
      {
        "type": "CNAME",
        "host": "www",
        "value": "smallbusiness.com"
      }
    ],
    "records_non_propagated": []
  }
}

​
Webhook payload breakdown

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.

​
Top-Level fields

  • 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").

​
Event type

  • type: Defines the type of event. Possible values:
    • "domain.added": Confirmation that DNS records have been added. For Entri Sell, it means the domain is registered and connected, while for Entri Connect, it indicates DNS records are added for an existing domain. If there is a delay in propagation, a "domain.propagated" event will be triggered once the records are fully propagated.
    • "domain.purchased": Indicates that the domain order creation has been completed.
    • "domain.propagated": You will receive this event if there is a delay between the propagation of records from the time the domain is connected through Entri.
    • "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).

​
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.
    • "failure": DNS record propagation has failed. This is triggered if the records are not propagated even after 72 hours.

  • dkim_status: The status of DKIM (DomainKeys Identified Mail) configuration. Possible values:

    • "pending": DKIM setup is pending.
    • "success": DKIM configuration has been successfully completed.
    • "failure": 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.
    • "failure": 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.

​
Advanced DMARC configuration feature

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).

​
Entri Secure status

  • 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.
    • "failure": SSL setup failed.

​
Entri Power status

  • 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.
    • "failure": Setup of advanced features failed.

​
CNAME and domain information

  • 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:

    ["domain1.com", "domain2.com", "domainN.com"]

  • 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.

​
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:

      ["path1", "path2", "pathN"]

  • records_non_propagated: An array of DNS records that have not yet propagated. The structure is the same as records_propagated.

​
Examples of key and value pairs

  • "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": "failure": The advanced feature configuration process has failed.
  • "cname_target": "my.saascompany.com": The CNAME target for Entri Power or Secure configuration.

​
Webhook updates

If any part of the webhook object is updated, subsequent webhooks will only include the updated fields. Example update:

{
  "id": "1234567890-abcdefg-1234567890",
  "propagation_status": "success",
  "updated_objects": ["propagation_status"]
}

​
Retry logic for propagation

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.

​
DKIM status notes

The dkim_status field is set to exempt if:

  • The user does not use Google or Microsoft email providers.
  • The Enable support for DKIM setting is disabled for your applicationId.

​
Webhook signatures

We highly recommend enabling webhook signatures for security. This helps ensure that webhooks are securely sent and verified.

Entri will concatenate the Id value of the webhook and the secret token from the dashboard, then generate a SHA-256 hash. This hash will be sent in the Entri-Signature header, like so:

Entri-Signature=e863e1f6370b60981bbbcbc2da3313321e65eaaac36f9d1262af415965df932

To verify this signature:

  1. Hash the received Id value using SHA-256 with your secret token.
  2. Compare this hash with the value in the Entri-Signature header.

If the hashes match, the request is authentic. If they do not, reject the request.

Power custom domainsAPI Reference