Hader

1. Authenticate the original request. The channel signature is checked against the raw request bytes. Re-serializing the payload before verification would change the bytes and make the check unreliable.
2. Resolve ownership from channel evidence. The callback address is treated as routing context, not sufficient proof of tenant ownership. Phone and channel metadata are matched to the organization that actually owns the connection.
3. Make receipt durable. Recognized messages are deduplicated using provider identity, direction, and organization scope. Unrecognized subscribed event types are parked before the endpoint acknowledges them, preserving a recoverable source event.
4. Create or recover conversation state. The contact, thread, message, delivery state, and source channel are reconciled inside tenant scope. A uniqueness race during thread creation is handled by recovering the row created by the competing request.
5. Evaluate suppression gates. Hader checks deployment and feature state, opt-out and block state, channel state, message age, explicit staff takeover, and whether a handset reply has already answered this particular customer message.
6. Build a grounded decision outside the database transaction. The model receives approved tenant data, while long-running inference is kept outside the short database transaction. Deterministic validators inspect the response and any proposed action.
7. Commit business state before claiming success. Orders and bookings must exist as structured records before the customer is told they were created. Server-side state, rather than a model-emitted total or marker, remains authoritative.
8. Deliver and reconcile asynchronously. Delivery status, retryable work, notifications, and downstream events continue through background processing. The persisted inbound message remains available even when inference or delivery fails later.

Embedded channel onboarding introduced an attribution problem that does not appear in a single-tenant webhook. A newly connected number can begin delivering through an application-level callback before its tenant-specific callback is the effective route. That means the organization named in the URL and the organization that owns the phone channel can legitimately differ.

My first implementation parked unhandled event fields, but review exposed two failure modes: the write was started without being awaited, and the callback-addressed tenant was being treated as the owner. A successful HTTP response could therefore precede durable storage, while a valid event could be credited to the wrong organization.

I changed the boundary in two ways. First, the system records both the callback context and the independently resolved channel owner rather than collapsing them into one identity. Second, parking is awaited before acknowledgment; if persistence fails, the endpoint returns a retryable failure instead of a success that would make the event unrecoverable. Ordinary message traffic bypasses this landing path and retains its normal deduplication flow.

This is intentionally a capture first, interpret later design. It adds storage and replay work, but it converts unknown event shapes from silent data loss into observable backlog. It also avoids guessing when an account-level payload lacks enough phone-level metadata to attribute safely.

Portal handoff is straightforward to model as durable conversation state: taking over a thread pauses automation until an explicit resume action. WhatsApp Coexistence creates a different race. A business owner can reply from the handset without creating a portal user action, including during the several seconds in which an automated draft is being generated.

Treating that handset reply as an assignment would be semantically false because no Hader user took ownership. Muting the thread forever would also be wrong because a later customer message may need automation again. I introduced a separate, forward-only handset-reply timestamp and compare it with the timestamp of the inbound customer message being considered. An older redelivery cannot move that state backward, and a new customer message is not suppressed by an unrelated historic reply.

The echo is also persisted as an operator-originated message so the inbox and reporting do not claim it as bot work. For the narrower in-flight race, the echo invalidates the active generation token; the sender checks that token again after generation and discards a superseded draft. Durable conversation state remains the long-lived guard, while fast invalidation narrows the window in which concurrent work can become stale.

This mechanism does not turn delivery into an exactly-once system. Provider retries are expected, event ordering is imperfect, and active-draft cancellation depends on a coordination layer. The design contains those conditions with forward-only state, message deduplication, and a final supersession check rather than assuming events arrive once and in order.

The real-time call service is kept outside Hader’s core request process because audio transport and conversational latency have a different failure profile from business records. The boundary is narrow: the dialed line resolves to one organization; Hader returns bounded, tenant-specific configuration and structured order or booking fields; the call service reports lifecycle events and invokes typed business operations.

The write contract tolerates retries and reordering. Call start is idempotent, transcript turns are unique within a call sequence, call end is write-once, and retrying an order for the same call returns the existing order instead of creating a second one. A worker closes calls that never receive a terminal event. These rules let the call transport retry without duplicating the customer’s operational record.

Orders, bookings, payment requests, and customer history still belong to Hader. The voice service does not receive a parallel source of truth or direct database ownership. This capability is deployed and used by active clients, but client identities, call volumes, and operating metrics are not published.

Repository history. My commits implement the voice gateway and multi-tenant phone configuration, order and booking submission, payment-link handoff, caller continuity, call cleanup, and targeted hardening. Later commits implement durable webhook parking, correction of tenant attribution, versioned consent gates, handset-reply capture, and automated-reply suppression.

Automated verification. The repository includes tests for voice authentication and organization scoping, phone-integration isolation, retry-safe call and order behavior, webhook signatures, tenant isolation, row-level policy drift, consent decisions, and related domain validators. Database uniqueness constraints provide the final deduplication boundary where concurrent requests can outrun application checks.

Operational verification. Voice changes were deployed and exercised in active use. The repository also documents deployment health checks, migrations, rollback behavior, and a formal handover. Those artifacts support implementation and operational ownership; they do not establish a public uptime, latency, model-accuracy, or autonomous-resolution metric.