Stay up to date with AI tools, model releases, and developer workflows that matter.
In a recent development, weekly. Free. One click to leave.
According to recent reports, 7 Day Free Trial. Cancel Anytime.
It has been revealed that A visitor clicks a search ad, submits a quote request, and calls your sales team ten minutes later. The form integration creates a CRM contact. The phone platform records a call. By Friday, the marketing report highlights two leads, while sales remembers one conversation that turned into a deal.
Sources indicate that both systems captured something useful. The problem is that neither record explains how the two interactions belong together.
A unified tracking pipeline gives forms and calls a common event format, preserves their acquisition context, and connects them to CRM outcomes. It also needs to survive a less tidy reality: repeated callbacks, missing campaign data, delayed updates, and a CRM that occasionally refuses requests.
Industry observers note that this tutorial builds the core of that pipeline with JavaScript and PostgreSQL. We will capture campaign parameters, define a shared event contract, and persist events alongside the work needed to deliver them. Provider authentication and CRM requests belong in adapters around this core, using the documentation for the services you choose.
Sources indicate that before writing an endpoint, decide what you are counting. A phone call can produce several status callbacks. A person can submit two forms. An existing customer can contact sales about a upcoming purchase.
Use separate identifiers for these different things:.
Recent findings suggest that this separation prevents two common mistakes. Deduplicating by call ID alone can discard later status updates. Counting every callback as a lead inflates demand.
Industry observers note that for this implementation, each event is unique within a tenant and source. A tenant is the business whose data you are processing; the source identifies a website or provider account. The same provider event ID can therefore appear in two accounts without causing a collision.
Sources indicate that keep the original interactions even after you connect them to one contact. The form and the call are both useful evidence. Your reporting layer decides whether they represent one opportunity.
Campaign parameters are easiest to capture when the visitor first arrives. Waiting until the form submission can lose them if the visitor has already moved to another page.
Google's campaign URL documentation explains the roles of utm_source, utm_medium, and utm_campaign. The following helper reads those fields and a few optional ones, without copying the entire query string:.
export function readCampaign(url) {.
const params = latest URL(url).searchParams;.
"utm_source", "utm_medium", "utm_campaign",.
"utm_id", "utm_content", "utm_term".
return Object.fromEntries(keys.flatMap(key => {.
const value = params.get(key)?.trim();.
return value && value.length <= 200.
In a recent development, the browser's URLSearchParams interface handles query parsing and decoding. It saves you from writing string-splitting code that breaks on encoded characters.
Run this helper through your site's existing consent and attribution flow. Where storage is permitted, associate the result with an opaque attribution reference in your backend and retain that reference through the visit. A later form submission sends the reference; the server resolves it within the correct tenant and visitor session. The form must still work when attribution storage is unavailable.
Keep first-touch and current-touch records separately if you need both. Overwriting the first campaign every time someone returns makes the eventual report answer a different question.
Recent findings suggest that treat campaign labels as untrusted input. Visitors can edit query strings and hidden fields. Validate them on the server, escape them when displayed, and never use them as authorization or as the sole evidence for commission payments. Avoid putting names, email addresses, or other personal information in UTM values.
Missing tags also need careful handling. An empty UTM object only tells you that no accepted UTM values were captured. Classifying a visit as direct, organic, or referral requires additional evidence and an explicit attribution rule.
Forms carry browser context naturally. Phone calls need a bridge between the number dialed and the marketing interaction that prompted the call.
Sources indicate that there are two useful levels of precision. A number assigned to one campaign can identify that campaign. Dynamic number insertion can support a more detailed association by displaying tracking numbers according to a visitor or session mapping. That association depends on the provider's number allocation and expiry rules.
Recent findings suggest that providers differ in how they implement this, and in what they expose beyond it, such as keyword-level reporting or conversation analysis. If you are still choosing one, this comparison of attribution software with call tracking is a useful starting point. At the integration boundary, check which event identifiers, attribution fields, delivery mechanisms, and authentication options your configured product exposes.
Recent findings suggest that keep that provider-specific work in an adapter. Its job is to turn an authenticated notification into your event contract and resolve any attribution reference supported by the provider's data. The application schema below is an internal contract; each provider adapter translates its documented payload into that contract.
Industry observers note that store the basis of a match with the attribution record. For example, session_match, campaign_number, and unknown make different levels of evidence visible to reporting. If a number has been reassigned, use the mapping valid when the call occurred, not whichever mapping happens to be current when the callback arrives. If the evidence is ambiguous, leave the association unresolved.
It has been revealed that caller ID is a separate concern. A shared office number, a withheld number, or an outdated contact record can make automatic identity matching unreliable. A confirmed CRM contact ID or an authenticated account provides a stronger link. Treat a matching phone number as a candidate for reconciliation rather than proof that two records belong to the same person.
Recent findings suggest that A shared event envelope lets the rest of your application work with a small, predictable vocabulary. Here is an illustrative call event:.
"occurred_at": "2026-11-06T10:14:00.000Z",.
"data": { "status": "completed" }.
The event ID identifies this occurrence. The interaction ID groups it with other events for the same call. contact_ref can remain empty until you have enough evidence to connect the interaction to a contact.
Keep contact details in a controlled contact store and campaign details in an attribution store. The references above point to those records; they are not credentials and must not grant access on their own.
The following factory checks the shared envelope. Each adapter still needs its own validation for provider fields and the contents of data.
"form.submitted", "call.started", "call.completed",.
export function makeEvent(input, trusted) {.
const ids = [trusted.tenantId, trusted.source,.
input.eventId, input.interactionId];.
if (ids.some(id => typeof id !== "string" ||.
!id.trim() || id.length > 200)) {.
throw new TypeError("Invalid event identifiers");.
throw new TypeError("Unsupported event type");.
const time = Date.parse(input.occurredAt);.
if (typeof input.occurredAt !== "string" ||.
fresh Date(time).toISOString() !== input.occurredAt) {.
throw new TypeError("Expected a canonical UTC timestamp");.
interaction_id: input.interactionId,.
contact_ref: input.contactRef ?? null,.
attribution_ref: input.attributionRef ?? null,.
Resolve trusted from server configuration and the authenticated integration. Never let a submitted tenant_id choose whose records a webhook can write. Resolve contact and attribution references within that same tenant.
It has been revealed that for a form, matter a submission ID and reuse it when retrying the same submission. Generate a fresh one when the visitor deliberately starts another inquiry. Preserve the originally accepted timestamp as well. For a phone event, prefer the provider's stable event ID. If the provider documents a sequence number, a call ID plus that sequence can identify an occurrence within a provider account.
Twilio's call resource documentation provides a concrete example: call progress callbacks include a SequenceNumber, and separate HTTP requests can arrive out of order. Preserve that sequence in the adapter. A late βringingβ event should remain in the history without replacing a newer terminal state.
Sources indicate that authenticate before calling this factory. Use the provider's supported validator and the exact request representation it requires. Twilio's webhook security guide describes signature validation, including the importance of the request URL and payload. Other providers may use different mechanisms. Public form endpoints need their own input limits, abuse controls, and appropriate CSRF protection.
Sources indicate that consider a failure between these two operations: the application saves an event, then crashes before scheduling its CRM revision. The event exists, but nothing is waiting to deliver it.
Industry observers note that A transactional outbox addresses that gap. Save the event and a delivery task in the same database transaction, then let a worker process the task. AWS explains this dual-write problem in its transactional outbox guidance.
According to recent reports, here is a compact schema. received_at records ingestion time, while the envelope retains the event's original occurred_at value.
received_at timestamptz NOT NULL DEFAULT now(),.
PRIMARY KEY (tenant_id, source, event_id).
id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,.
available_at timestamptz NOT NULL DEFAULT now(),.
attempts integer NOT NULL DEFAULT 0,.
UNIQUE (tenant_id, source, event_id),.
FOREIGN KEY (tenant_id, source, event_id).
REFERENCES lead_events (tenant_id, source, event_id).
According to recent reports, the ingestion function below accepts a pg pool and a normalized event. Install pg in your Node.js project, save the function as persist.mjs, and initialize the pool using your application's database configuration.
export async function persistEvent(pool, event) {.
const key = [event.tenant_id, event.source, event.event_id];.
const values = [...key, JSON.stringify(event)];.
const client = await pool.connect();.
await client.query("BEGIN ISOLATION LEVEL READ COMMITTED");.
const inserted = await client.query(`.
(tenant_id, source, event_id, payload).
ON CONFLICT (tenant_id, source, event_id) DO NOTHING.
const existing = await client.query(`.
SELECT payload = $4::jsonb AS matches.
WHERE tenant_id = $1 AND source = $2 AND event_id = $3.
if (!existing.rows[0]?.matches) {.
const error = new Error("Event ID reused with new data");.
INSERT INTO crm_outbox (tenant_id, source, event_id).
return { inserted: inserted.rowCount === 1 };.
await client.query("ROLLBACK");.
Industry observers note that postgreSQL's INSERT documentation defines the conflict handling used here. The unique key makes duplicate detection hold across application processes. A duplicate with the same normalized payload creates no second task; reuse of the key with different data raises a conflict for investigation.
This depends on immutable event bodies. Do not add a fresh receipt timestamp, random identifier, or current CRM status to the normalized payload on each delivery. Store later enrichment separately or emit a upcoming event. Otherwise an ordinary retry will appear to be a conflicting event.
The function deliberately uses one database client throughout the transaction, as required by the node-postgres transaction documentation. Parameter values are passed separately from SQL, following its parameterized query guidance.
According to recent reports, after this function commits, acknowledge the notification using the response expected by the sender. An identical duplicate should also receive a successful acknowledgement. If persistence fails, return the appropriate failure response and rely on the configured retry or reconciliation process. A success response sent before durable storage can turn a temporary database failure into a missing event.
For voice integrations, distinguish an informational status callback from a request asking your application how to handle a live call. They can require different response bodies, as explained in the Twilio webhooks FAQ.
The outbox gives you durable work to process. It does not make a remote CRM operation happen exactly once.
Imagine the CRM saves an revision, but the worker crashes before setting processed_at. When the task runs again, the same request may reach the CRM twice. Design for that case explicitly.
Sources indicate that use a stable external identifier for each contact, opportunity, and activity, and check which deduplication guarantees the destination supports. HubSpot's contacts API documentation, for example, describes upserts using unique properties. Support for a contact upsert does not automatically make every associated activity or workflow idempotent. Verify the behavior of each operation you send.
Industry observers note that if the destination cannot deduplicate a create request and a timeout leaves its result uncertain, reconcile that operation before repeating it. A local βsentβ flag alone cannot prove whether the remote write happened.
The worker should claim due tasks, commit a recoverable lease, and perform network calls outside the database transaction. A lease allows another worker to recover work after a crash. When multiple workers poll the outbox, PostgreSQL's SKIP LOCKED behavior can help claim separate rows, but the lease and its recovery logic still need to be implemented.
Recent findings suggest that retry transient failures with increasing delays and jitter. Respect the destination's rate-limit instructions. Send persistent validation failures to a review queue with a useful error category, and provide a way to replay them after correction. The schema above is the ingestion foundation; a production worker needs lease fields, failure details, and a retry policy appropriate to its destination.
It has been revealed that also preserve ordering where it changes meaning. If two events upgrade the same contact or opportunity, process them serially or reject stale updates using a stored version. A historical event should not move a won opportunity back to an earlier stage.
Once both channels reach the CRM, connect them to the result the business cares about. A form submission is an inquiry. A completed phone call is a technical outcome. Neither alone establishes that a lead qualified or a purchase happened. If agents record call dispositions, such as whether a call was qualified or transferred to a closer, that field is a richer signal than call completion status alone.
According to recent reports, have the CRM or the system that owns the transaction emit explicit outcome events, such as lead.qualified and deal.won. Include the internal opportunity ID and the original outcome time. Model reversals or cancellations explicitly if they affect revenue reporting.
It has been revealed that then choose the unit behind each metric. For a report about opportunities acquired during a particular month, a qualification rate can use qualified opportunities divided by all opportunities in that acquisition cohort. Counting qualification events received during the month would answer a different question and could include older inquiries.
Recent findings suggest that deduplicate opportunities before calculating channel totals. A person who submits a form and calls about the same purchase should retain both interactions, while the opportunity receives credit according to your chosen attribution rule. Label that rule in the report so first-touch and last-touch numbers are not compared as though they measure the same thing.
According to recent reports, measure data quality alongside performance. Track unresolved attribution, duplicate deliveries, ingestion failures, and the age of the oldest pending outbox task. Once several sources and destinations feed the same reports, a data observability platform can watch these signals across the whole pipeline instead of relying on checks inside a single worker. An apparently quiet campaign may actually have a broken integration.
In a recent development, operational logs should contain enough context to investigate failures without becoming another customer database. Use internal references and error categories, and avoid dumping webhook bodies into logs. The OWASP Logging Cheat Sheet provides guidance on excluding or protecting sensitive values.
A successful form submission proves little about retries or missing data. Before connecting production traffic, test the cases that could distort reporting or lose an inquiry.
Run database cases against PostgreSQL with separate connections so the tests exercise actual constraints and transaction behavior. Use the provider's test tools or signed fixtures for webhook authentication. Test CRM retries against a sandbox with the destination's real duplicate-handling rules.
Industry observers note that start rollout with one form and one phone source. Trace a known inquiry from its captured campaign through its interactions to its CRM outcome. Reconcile event totals against the source systems over the same time window, allowing for delivery delays. Expand once that path is explainable and failures are visible.
Industry observers note that the same adapter pattern extends to inquiries that start offline, such as leads collected at a trade show and exported as a CSV or XLSX file. Import each row as a form.submitted event with the event as its source, a stable row identifier as event_id, and the original capture time as occurred_at. Because the outbox treats an identical event as a duplicate, re-importing the same export wonβt create a second CRM task.
What is a unified lead tracking pipeline?
Industry observers note that it is a workflow that converts inquiries from different channels into a shared data model, preserves their acquisition context, and connects them to business outcomes. Forms and calls keep their own interaction records, while contacts and opportunities provide the relationships needed for reporting.
Can I connect a phone call to a website visit?
Recent findings suggest that sometimes. Dynamic number insertion can provide a session or visitor association when the provider's mapping is available and valid. A campaign-specific number usually supports campaign-level attribution. If the caller uses a saved number, switches devices, or calls after a mapping expires, the available evidence may be less precise.
How do I prevent duplicate leads?
According to recent reports, handle duplicate delivery and identity resolution separately. Stable event IDs and a database constraint prevent repeated notifications from producing repeated work. Connecting several interactions to one contact or opportunity requires a separate matching policy, with ambiguous cases left unresolved until there is enough evidence.
Should a completed call count as a conversion?
It has been revealed that only if that is the conversion your report explicitly measures. A completed call does not establish that a prospect qualified or bought something. Keep technical call status separate from CRM outcomes and use the latter when reporting qualified demand or revenue.
Do I need a message broker for this architecture?
Sources indicate that you can begin with PostgreSQL and an outbox worker if that setup meets your throughput and latency needs. A broker becomes useful when several consumers need independent delivery, or when buffering and scale justify the additional operations. In either case, retries still require idempotent consumers.
What happens when tracking consent is unavailable?
According to recent reports, keep the inquiry flow usable and apply your site's existing consent rules to optional attribution collection and storage. Accept permitted form or call data, leave unavailable attribution empty, and avoid reconstructing a visitor identity through fingerprinting. Reports should expose that missing context instead of inventing a campaign match.
Industry observers note that 7 Day Free Trial. Cancel Anytime.
