Webhooks Overview

​

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

​

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.

​

Overview and Webhook Structure

{
  "id": "028b5078-8fed-4ffb-8e3e-3e6e6d8214b4",
  "user_id": "sample-user",
  "domain": "smallbusiness.com",
  "provider": "ionos.com",
  "type": "domain.added",
  "propagation_status": "success",
  "dkim_status": "success",
  "redirection_status": "exempt",
  "ssl_status": "success",
  "setup_type": "automatic",
  "secure_status": "success", //Only for Entri Secure usage
  "power_status" : "success", //Only for Entri Power usage
  "cname_target": "my.saascompany.com", //Only for Entri Power and Secure usage
  "purchased_domains": ["domain1.com",...,"domainN.com"], //Only for Entri Sell usage
  "data": {
    "records_propagated": [
      {
        "type": "A",
        "host": "smallbusiness.com",
        "value": "54.153.2.220"
      },
      {
        "type": "CNAME",
        "host": "www",
        "value": "smallbusiness.com"
      }
    ],
    "records_non_propagated": [],
    "updated_objects": [
      "propagation_status",
      "ssl_status"
    ]
  }
}

​

Webhook Management Endpoints

​

Trigger propagation re-check (async)

Tip: The jobId required for this endpoint can be obtained from the onSuccess browser event once the flow finishes successfully.

POST https://api.goentri.com/connect/propagation/recheck/:job_id
Header "Authorization: [JWT authorization]"
Header "applicationId: [yourApplicationID]"

​

Alternative UI-based option

​

Headers

​

Path Parameters

​

Request Body

​

Response

• 202 Accepted if the re-check was queued successfully.

{
  "jobId": "9c128fe4-63cd-4ec4-9ae8-8a9d06c0e6de",
  "queued": true,
  "message": "Propagation re-check has been queued. A webhook will be sent with the result.",
  "enqueuedAt": "2025-11-05T18:22:00Z"
}

​

Webhook behavior

• Performs one immediate propagation re-check and sends a webhook with the latest propagation status; no continuous propagation retries follow this manual re-check.
• Includes "manual_retry": true in the webhook body.
• Follows the standard delivery policy with up to 3 attempts if the receiver is unavailable.
• Logs a new webhook attempt entry; existing webhook logs are not overridden.
• Uses the same execution codepath as the private Dashboard action for this functionality.

​

Cooldown

• 429 Too Many Requests with message: "You can only trigger the check once every 5 mins"
  (Servers may also include Retry-After: 300.)

​

Error Responses

​

Example cURL

curl -s -X POST \
  "https://api.goentri.com/connect/propagation/recheck/9c128fe4-63cd-4ec4-9ae8-8a9d06c0e6de" \
  -H "Authorization: Bearer <JWT>" \
  -H "applicationId: <YOUR_APP_ID>"

​

Get last webhook by job ID

Tip: You can obtain the jobId value directly from the onSuccess browser event, which is triggered when the user reaches the Congratulations screen.

GET https://api.goentri.com/connect/webhooks/last/:job_id
Header "Authorization: [JWT authorization]"
Header "applicationId: [yourApplicationID]"

​

Headers

​

Path Parameters

​

Sample Response

{
  "id": "d6a6b6c4-45f3-42a2-8bb1-3c92debf47e2",
  "job_id": "9c128fe4-63cd-4ec4-9ae8-8a9d06c0e6de",
  "domain": "example.com",
  "type": "domain.propagation.success",
  "manual_retry": false,
  "status": "delivered",
  "sentAt": "2025-11-05T18:22:00Z",
  "payload": {
    "domain": "example.com",
    "job_id": "9c128fe4-63cd-4ec4-9ae8-8a9d06c0e6de",
    "propagation_status": "success",
    "records_checked": [
      { "type": "CNAME", "host": "www", "value": "myapp.com" }
    ]
  }
}

​

Error Responses

​

Notes

• This endpoint is read-only and returns the last logged webhook event associated with the provided job_id.
• It retrieves data from the webhook logs table and does not resend or trigger new webhooks.
• Only returns the most recent webhook entry for that job.

​

Provider Health

GET https://api.goentri.com/providers_health
Header "Authorization: [JWT authorization]"
Header "applicationId: [yourApplicationID]"

​

Response body

{
  "message": "success",
  "data": [
    {
      "provider": "IONOS",
      "enabled": true
    },
    {
      "provider": "Enom",
      "enabled": true
    },
    {
      "provider": "Amazon Route 53",
      "enabled": true
    },
    ...
  ]
}

​

Entri Webhook Signature Verification

​

Enforcing Webhook Source IP (Optional)

​

Signature Timestamp Header

​

Signature Verification Methods

​

Signature V3 (Recommended)

• Body binding: the HMAC is computed over the raw HTTP request body, so any tampering with the payload invalidates the signature. V1 and V2 sign only identifiers and timestamps, not the body contents.
• Replay protection: the Entri-Timestamp value is embedded in the signed message, so a captured valid request cannot be replayed after 300 seconds.

​

Header value format

Entri-Signature-V3: sha256=<lowercase hex digest>

​

How to verify

1. Read Entri-Timestamp. Reject the request if abs(now - timestamp) > 300 seconds.
2. Build the signed payload by concatenating: the timestamp string, a literal ., then the raw HTTP request body bytes.
3. Compute HMAC-SHA256 with your client_secret as the key over that payload.
4. Hex-encode the result and prepend sha256=.
5. Compare to the Entri-Signature-V3 header value using a constant-time comparison.

​

Verification examples

import hmac
import hashlib
import time

def verify_entri_signature_v3(
    raw_body: bytes,
    headers: dict,
    client_secret: str,
    max_age_seconds: int = 300,
) -> bool:
    timestamp = headers.get("Entri-Timestamp", "")
    signature = headers.get("Entri-Signature-V3", "")

    try:
        if abs(time.time() - int(timestamp)) > max_age_seconds:
            return False
    except (ValueError, TypeError):
        return False

    signed_payload = f"{timestamp}.".encode() + raw_body
    expected = "sha256=" + hmac.new(
        key=client_secret.encode(),
        msg=signed_payload,
        digestmod=hashlib.sha256,
    ).hexdigest()

    return hmac.compare_digest(expected, signature)

const crypto = require("crypto");

function verifyEntriSignatureV3(rawBody, headers, clientSecret, maxAgeSeconds = 300) {
  // Header names are lowercased by most Node.js HTTP frameworks
  const timestamp = headers["entri-timestamp"] ?? headers["Entri-Timestamp"] ?? "";
  const signature = headers["entri-signature-v3"] ?? headers["Entri-Signature-V3"] ?? "";

  const ts = parseInt(timestamp, 10);
  if (isNaN(ts) || Math.abs(Date.now() / 1000 - ts) > maxAgeSeconds) {
    return false;
  }

  // rawBody must be the original Buffer — do not pass a re-serialized JSON string
  const body = Buffer.isBuffer(rawBody) ? rawBody : Buffer.from(rawBody);
  const signedPayload = Buffer.concat([Buffer.from(`${timestamp}.`), body]);
  const expected = "sha256=" + crypto
    .createHmac("sha256", clientSecret)
    .update(signedPayload)
    .digest("hex");

  try {
    return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
  } catch {
    return false;
  }
}

<?php

function verifyEntriSignatureV3(
    string $rawBody,
    array $headers,
    string $clientSecret,
    int $maxAgeSeconds = 300
): bool {
    // PHP header arrays may use different casing depending on the framework
    $timestamp = $headers[‘Entri-Timestamp’] ?? $headers[‘entri-timestamp’] ?? ‘’;
    $signature  = $headers[‘Entri-Signature-V3’] ?? $headers[‘entri-signature-v3’] ?? ‘’;

    if (!is_numeric($timestamp) || abs(time() - (int) $timestamp) > $maxAgeSeconds) {
        return false;
    }

    // Concatenate timestamp, literal dot, and raw body — do not JSON-decode first
    $signedPayload = $timestamp . ‘.’ . $rawBody;
    $expected = ‘sha256=’ . hash_hmac(‘sha256’, $signedPayload, $clientSecret);

    return hash_equals($expected, $signature);
}

​

Signature V2

​

How to verify

1. Read the webhook payload’s id field.
2. Read the Entri-Timestamp header (epoch seconds).
3. Build the canonical message: webhook_id + timestamp + client_secret (concatenated, no separators).
4. Compute SHA256(canonical_message) and hex-encode it.
5. Compare the result to the Entri-Signature-V2 header using a constant-time comparison.
6. Enforce a freshness window (for example, 5 minutes) using the timestamp.

​

Verification example (Python)

import hashlib
import hmac
import time

def verify_entri_signature_v2(
    webhook_id: str,
    client_secret: str,
    received_signature: str,
    received_timestamp: str,
    max_age_seconds: int = 300,
) -> bool:
    try:
        if int(time.time()) - int(received_timestamp) > max_age_seconds:
            return False

        expected = hashlib.sha256(
            webhook_id.encode() + received_timestamp.encode() + client_secret.encode()
        ).hexdigest()

        return hmac.compare_digest(expected, received_signature)
    except (ValueError, TypeError, AttributeError):
        return False

​

Signature V1 (Legacy)

​

Verification example (Python)

import hashlib
import hmac

def verify_entri_signature_v1(
    webhook_id: str,
    client_secret: str,
    received_signature: str,
) -> bool:
    expected = hashlib.sha256(
        webhook_id.encode("utf-8") + client_secret.encode("utf-8")
    ).hexdigest()
    return hmac.compare_digest(expected, received_signature)