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

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