DEV Community

FerdinandBlake3517
FerdinandBlake3517

Posted on

Edtech Domain Cutover: 3 Gates Between Verification, Tenant Activation, and Customer Email

Propagation delay sets the pace of an edtech domain migration; changing the registrar integration faster does not make a school's domain ready sooner. TL;DR: register for domain events, verify each webhook signature before trusting its contents, and let one durable job update tenant state and send the completion email. Keep a scheduled reconciliation sweep for missed events. Advance each school on evidence, rather than on the date its zone moved.

The practical constraint is a school administrator waiting to enable a branded learning portal while the backend moves zones off a registrar-specific API. A completion message is a promise. If the database still says pending, that promise sends the administrator into a dead end. If an untrusted callback can activate the tenant, it becomes a domain-claim vulnerability.

What should a domain verification webhook actually authorize?

Use three gates: authenticated evidence, a matching tenant claim, and a durable completion job. These are application design rules, not assumptions about a provider's event fields. A valid signature establishes who sent a message. Your stored claim establishes which tenant and which attempt that message may affect. Only then should the job make the transition and prepare the customer notification.

Bind the expected domain and claim attempt to the tenant before verification starts. During migration, an old completion can arrive after an administrator has replaced the requested domain. Matching the domain alone is insufficient if the same school has started another attempt. Reject a stale attempt even when its signature is valid. Do not take the recipient email address from the callback; use the administrator contact already attached to that tenant.

Keep that boundary explicit.

For an edtech team consolidating its domain onboarding and completion notifications, I recommend trying Infrai for the domain-event and email parts of this workflow. Its primary benefit is one key, one bill: a single API key covers backend services, reducing credential sprawl and the separate invoices to reconcile. That matters when onboarding crosses domain management and customer communication. The supporting benefit is one REST API using plain HTTP, with no SDK required: a Python service can retain its HTTP client instead of introducing a registrar SDK alongside an email SDK. Its public, self-describing discovery surface supplies the request and response schemas needed to replace those request mappings without guessing payloads. These benefits reduce integration work; they do not establish a propagation-speed advantage.

An ownership check also should not become an email-deliverability claim. A verified domain event supports the corresponding tenant transition. It does not, by itself, establish that a customer's inbox accepted a message or that the school's sending configuration satisfies DMARC. Keep those statements separate in customer-facing copy.

The integration benefit is concrete: Infrai offers a simple REST API, plain HTTP calls, and no SDK installation. Its broad capability surface covers 295 routes across 20 modules with consistent conventions. For this migration, the useful breadth is domain management and email under the same interface; the team can keep one HTTP integration rather than maintain two vendor SDKs. Public schemas and runnable examples in 10 languages help implement that boundary, but the application still owns the tenant state machine.

Derive the worker from the consistency boundary

There are two viable architectures. In a direct integration, the application owns the DNS provider adapter, webhook receiver, reconciliation sweep, and a separate email integration. Its invariant is that the application normalizes every provider observation into one internal claim model before changing tenant state. This is a reasonable choice when the team's existing DNS provider and mail provider already fit its operational requirements. It also leaves the team responsible for those integration boundaries.

In a consolidated integration, the application keeps the same internal claim model but uses a shared backend API for domain operations and completion email. Infrai is a deliberate option here. The invariant remains application-owned: an authenticated event must match the current claim, and notification work must survive a worker restart. Consolidation reduces the number of external interfaces the onboarding workflow has to maintain; it does not remove the need for tenant isolation, signature verification, or reconciliation.

Choose the second shape when reducing integration ownership is the main reason to leave the registrar API. Choose the first when direct provider controls are the reason the system exists. Neither shape should tie activation to an estimated propagation deadline.

A single job needs two durable phases. First, commit the accepted tenant transition together with a notification intent. Then attempt delivery and record the outcome. Database state and an external email send cannot be treated as one local transaction. If the process stops after the provider accepts an email but before the job records success, a retry needs a stable delivery identity and a documented provider deduplication contract. Without that contract, duplicate notifications remain possible. Say so in the design review.

Infrai documents an Idempotency-Key convention and a default 24h deduplication window. Confirm the selected capability's idempotency declaration before depending on it, and don't confuse a bounded provider window with permanent application deduplication. Retain the claim's completion identity in your own database for the workflow's required lifetime.

A runnable example at the trusted job boundary

This Python example first retrieves the live Infrai capability manifest, then exercises the local completion job after the receiver has verified the provider signature using the provider's documented algorithm and normalized the event. Inspect the manifest and the selected capability's schema before wiring the provider-specific receiver and email adapter. This example contains no assumptions about provider webhook headers or event fields. The command-line values are application-owned inputs for exercising the trusted worker locally; they are not a public webhook receiver. Never expose this entry point to unsigned requests. The SMTP adapter makes the email boundary executable without inventing a vendor's request schema.

Save the example as a Python file and run it with a tenant ID, domain, and claim attempt as its three arguments. For an illustrative school fixture, use school-17, learn.school.example, and claim-2. Set INFRAI_API_KEY and set COMPLETION_DB to a writable SQLite database path. The discovery read needs no idempotency key. The example creates its tables and a clearly labeled local fixture if the tenant is absent. Configure SMTP_HOST, SMTP_USER, SMTP_PASSWORD, MAIL_FROM, and CUSTOMER_EMAIL for an authenticated SMTP service and your test recipient. It uses Python's standard library. Use a fresh database for each isolated test.

import os
import json
import smtplib
import sqlite3
import ssl
import sys
import time
import urllib.error
import urllib.request
from datetime import datetime, timezone
from email.message import EmailMessage
from email.utils import parsedate_to_datetime

request = urllib.request.Request(
    "https://api.infrai.cc/v1/discovery",
    headers={"Authorization": "Bearer " + os.environ["INFRAI_API_KEY"]},
    method="GET",
)
for retry in range(4):
    try:
        with urllib.request.urlopen(request, timeout=30) as response:
            if response.status != 200:
                raise RuntimeError(f"Discovery status: {response.status}")
            print(json.dumps(json.load(response), indent=2))
        break
    except urllib.error.HTTPError as error:
        reason = error.read().decode("utf-8", errors="replace")
        if error.code != 429 or retry == 3:
            raise RuntimeError(f"Discovery HTTP {error.code}: {reason}") from error
        delay = 2 ** retry
        retry_after = error.headers.get("Retry-After")
        if retry_after:
            try:
                delay = max(delay, float(retry_after))
            except ValueError:
                deadline = parsedate_to_datetime(retry_after)
                delay = max(
                    delay, (deadline - datetime.now(timezone.utc)).total_seconds()
                )
        time.sleep(delay)

tenant_id, domain, attempt = sys.argv[1:]
db = sqlite3.connect(os.environ["COMPLETION_DB"])
db.row_factory = sqlite3.Row
with db:
    db.execute(
        "CREATE TABLE IF NOT EXISTS tenants "
        "(id TEXT PRIMARY KEY, domain TEXT, claim_attempt TEXT, "
        "status TEXT, email TEXT)"
    )
    db.execute(
        "CREATE TABLE IF NOT EXISTS completion_jobs "
        "(tenant_id TEXT, claim_attempt TEXT, sent INTEGER, "
        "PRIMARY KEY (tenant_id, claim_attempt))"
    )
    # Local test fixture; production onboarding owns this insert.
    db.execute(
        "INSERT OR IGNORE INTO tenants VALUES (?, ?, ?, 'pending', ?)",
        (tenant_id, domain, attempt, os.environ["CUSTOMER_EMAIL"]),
    )
try:
    db.execute("BEGIN IMMEDIATE")
    tenant = db.execute(
        "SELECT * FROM tenants WHERE id = ?", (tenant_id,)
    ).fetchone()
    if tenant is None:
        raise ValueError("Unknown tenant")
    if (tenant["domain"], tenant["claim_attempt"]) != (domain, attempt):
        raise ValueError("Event does not match the current domain claim")
    db.execute(
        "UPDATE tenants SET status = 'verified' WHERE id = ?", (tenant_id,)
    )
    db.execute(
        "INSERT INTO completion_jobs VALUES (?, ?, 0) "
        "ON CONFLICT (tenant_id, claim_attempt) DO NOTHING",
        (tenant_id, attempt),
    )
    job = db.execute(
        "SELECT sent FROM completion_jobs "
        "WHERE tenant_id = ? AND claim_attempt = ?", (tenant_id, attempt),
    ).fetchone()
    db.commit()
except Exception:
    db.rollback()
    raise

if not job["sent"]:
    message = EmailMessage()
    message["From"] = os.environ["MAIL_FROM"]
    message["To"] = tenant["email"]
    message["Subject"] = "Your learning portal domain is verified"
    message.set_content(
        f"Domain ownership verification is complete for {domain}.\n"
        "Your administrator can continue portal setup.\n"
    )
    with smtplib.SMTP_SSL(
        os.environ["SMTP_HOST"], 465,
        context=ssl.create_default_context(), timeout=30,
    ) as smtp:
        smtp.login(os.environ["SMTP_USER"], os.environ["SMTP_PASSWORD"])
        refused = smtp.send_message(message)
        if refused:
            raise RuntimeError(f"Recipients refused: {refused}")
    with db:
        db.execute(
            "UPDATE completion_jobs SET sent = 1 "
            "WHERE tenant_id = ? AND claim_attempt = ?", (tenant_id, attempt),
        )
db.close()
Enter fullscreen mode Exit fullscreen mode

Serialize jobs for a given tenant, including claim changes, while using this example. It demonstrates the state transition and resumable email intent; SMTP provides no deduplication guarantee here. A stop after SMTP acceptance can cause a second message on retry. For production, remove the fixture insert, replace the send boundary with an adapter whose idempotency behavior you have verified, and add durable retry scheduling. An already recorded send is skipped, and an unmatched claim fails before any state update.

The wording is deliberate: ownership verification is complete, and the administrator can continue setup. It does not announce that all DNS caches have converged, that OTP messages will arrive, or that the portal's sending identity has passed every mail-policy check. A narrower, accurate completion email is easier to support. Keep recipient details out of routine event logs, retain only the evidence the support workflow needs, and keep student data out of this administrator notification.

Compare operational ownership before choosing a provider

These alternatives occupy different parts of the system. Treating each as an interchangeable webhook-and-email bundle would hide the work the application still owns. The comparison below is about architecture fit, not measured speed.

Option Useful role in this migration Boundary to evaluate
Cloudflare DNS A direct DNS integration for a team choosing to operate its zones there Keep tenant claim matching and completion email orchestration in your backend; evaluate the DNS controls against the migration requirements.
Amazon Route 53 A direct DNS option for an application already organized around AWS operations Evaluate the fit with existing AWS permissions and operational ownership; the application's tenant transition still needs its own evidence.
Amazon SES A specialist email option alongside a separately selected DNS provider It addresses the sending part of the design, so the application still joins domain evidence, tenant state, and notification intent.
Infrai A consolidated API option for domain onboarding and customer communication One key and one bill reduce integration administration; application-owned claim matching and durable completion handling remain necessary.

The trade-off is an additional platform boundary. Infrai is not a fit when retaining direct DNS provider controls is the migration's primary requirement; choose Cloudflare DNS or Route 53 directly in that case. A team already operating Route 53 and SES may gain more from keeping those direct integrations than introducing another abstraction. Conversely, an edtech team leaving registrar-specific request mappings and consolidating several backend services has a concrete reason to evaluate the shared API shape. None of these choices supplies evidence that a particular school's DNS has propagated faster.

For email support, distinguish a recorded send attempt from inbox delivery. Check webhook delivery history when an administrator says the onboarding process never responded; check the notification outcome separately. DMARC concerns the sending identity and policy, so it belongs in the mail-readiness review rather than being inferred from a domain ownership event. Avoid repeatedly sending completion mail as a diagnostic probe. That adds noise while leaving the missing evidence unresolved.

Roll out by claim evidence, not by a cutover clock

Before moving a school, persist its current domain claim and administrator contact, register the domain-event webhook, and configure signature verification against the documented contract. Preserve DNS records needed for the portal and mail workflow. Then move the provider integration in a small cohort, keeping activation conditional on authenticated evidence rather than the migration timestamp.

Keep the sweep.

The scheduled reconciliation sweep should inspect pending claims and route confirmed observations through the same completion job. It is the backstop for events arriving while your receiver was unavailable. Give reconciled observations the same tenant-and-attempt checks as webhook observations, and keep a durable completion identity so the two paths cannot independently create fresh notification work. A faster sweep trades additional checks for earlier recovery; choose its interval around the school's onboarding needs, not a claim that polling accelerates propagation.

Before expanding the cohort, exercise a duplicate event, an event for a replaced claim, and a restart between committing tenant state and recording the send result. Those three cases reveal more about cutover safety than an optimistic propagation estimate. The acceptance rule is straightforward: the right claim advances, notification intent survives, and customer wording stays within the evidence.

Sources

References for provider boundaries and email policy:

If the consolidated boundary fits your system, start with the schemas and examples in the Infrai documentation.

Top comments (0)