​

Example webhook payload

{
  "id": "1234567890-abcdefg-1234567890",
  "user_id": "your-provided-user-id",
  "domain": "example.com",
  "subdomain": "shop",
  "provider" : "cloudflare",
  "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

​

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").
• provider: The domain’s provider associated with the event (e.g. "cloudflare").

​

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.
  • "api": The setup was performed using the Entri Sell Enterprise Api

​

Advanced DMARC configuration feature

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

• 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

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

​

Propagation retries

​

Connection failures retries

​

DKIM status notes

• 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

​

Enforcing Webhook Source IP (Optional)

​

Signature Timestamp Header

​

Signature Verification Methods

​

Signature V2 (Recommended)

​

How It Works

1. Read the webhook payload’s id (or Id).
2. Read the Entri-Timestamp header (epoch seconds).
3. Build the canonical message: "{webhook_id}.{timestamp}".
4. Compute HMAC_SHA256(secret, canonical_message) and hex-encode it.
5. Compare the result to the value in the Entri-Signature-V2 header.
6. Enforce a freshness window (for example, 5 minutes) using the timestamp to prevent replay.

​

Required Components

1. Webhook payload’s id value
2. Client secret from your Entri dashboard
3. Entri-Timestamp header — Unix timestamp used for Signature V2 verification
4. Entri-Signature-V2 header

​

Signature V2 Verification Example (Python)

import hashlib
import hmac
import time

def validate_entri_signature_v2(
    webhook_id: str,
    client_secret: str,
    received_signature: str,
    received_timestamp: str,
    max_age_seconds: int = 300
) -> bool:
    """
    Validate the Entri-Signature-V2 webhook signature.
    
    Args:
        webhook_id: The webhook ID from request body["id"]
        client_secret: Your client secret
        received_signature: The 'Entri-Signature-V2' header value
        received_timestamp: The 'Entri-Timestamp' header value
        max_age_seconds: Maximum allowed age of request (default: 5 minutes)
    
    Returns:
        True if signature is valid and fresh, False otherwise
    """
    try:
        # Verify timestamp freshness (prevent replay attacks)
        current_time = int(time.time())
        request_time = int(received_timestamp)
        if current_time - request_time > max_age_seconds:
            return False
        
        # Recreate the signature
        expected_signature = hashlib.sha256(
            webhook_id.encode() + received_timestamp.encode() + client_secret.encode()
        ).hexdigest()
        
        # Constant-time comparison
        return hmac.compare_digest(expected_signature, received_signature)
        
    except (ValueError, TypeError, AttributeError):
        return False

​

Signature V1 (Legacy)

1. The entire webhook payload (as a JSON string) is concatenated with your client secret.
2. A SHA-256 hash of this string is computed.
3. The resulting hash is sent in the Entri-Signature header.

​

Signature V1 Verification 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