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",
  "monitor_status": "pending",
  "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": 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.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).

​

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.

​

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.
  • "failed": SSL setup failed.
  • "exempt": Entri Secure does not apply to the current flow.

​

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.
  • "failed": Setup of advanced features failed.
  • "exempt": Entri Power does not apply to the current flow.

​

Entri Monitor status

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

  Copy

  Ask AI

  ["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:

    Copy

    Ask AI

    ["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": "failed": 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 include ALL 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.

​

Entri Webhook Signature Verification

​

Overview

This documentation describes how to verify Entri webhook signatures using the payload ID signature method (recommended).

​

How It Works

When Entri sends a webhook, it:

1. Takes the payload’s Id value
2. Concatenates it with your secret token
3. Generates a SHA-256 hash of this concatenated string
4. Sends this hash in the Entri-Signature header

​

Implementation Details

​

Required Components

1. Webhook payload’s Id value
2. Secret token from your Entri dashboard
3. Entri-Signature header from the webhook request

​

Code Example

import hashlib

def verify_webhook_signature(webhook_id: str, secret_token: str, received_signature: str) -> bool:
    """
    Verify the authenticity of an Entri webhook request.

    Args:
        webhook_id (str): The Id value from the webhook payload
        secret_token (str): Your secret token from the Entri dashboard
        received_signature (str): The value from the Entri-Signature header

    Returns:
        bool: True if signature is valid, False otherwise
    """
    hash_obj = hashlib.sha256(webhook_id.encode('utf-8'))
    hash_obj.update(secret_token.encode('utf-8'))
    calculated_signature = hash_obj.hexdigest()

    return calculated_signature == received_signature