Design a Lead Handoff That Survives Retries

Automation is a handoff between systems with imperfect timing and delivery. A request can time out after the destination has already processed it. An event can arrive twice. A destination can reject data that looked valid in the source. Treat these as normal design cases rather than rare surprises.

Start with the business operation you want to happen once. This tutorial uses a lead-to-CRM handoff, but it does not connect a CRM or send customer data. The browser simulator illustrates duplicate handling only. Production reliability requires durable storage, concurrency control and a recovery process.

1. Define the event and authoritative source

Write what happened, which system is allowed to assert it and which fields the destination needs. “Lead accepted” should come from the system that accepted the enquiry, not a button click. Record an event version and a stable operation reference so changes can be managed without guessing which payload a consumer received.

Minimize data. Use an internal reference when the destination can retrieve the necessary information through an authorized route. Keep credentials out of payload examples, logs and screenshots. Define who may access any customer details and how long they are retained before choosing the automation product.

2. Choose an idempotency key and scope

Decide which repeated requests represent the same business operation. A source event ID may be suitable; a contact email alone often is not, because one person can legitimately create several requests. Include the operation type or version where necessary so unrelated actions do not accidentally block each other.

Store the key and processing state durably at the system that must prevent the duplicate effect. A check-then-write without atomic protection can fail when two requests arrive together. Use your database or provider’s supported uniqueness and idempotency mechanism, and test concurrency rather than relying on a single browser session.

See the actual example

3. Model received, processing and completed states

Document the transition from receipt through validation to the completed destination action. Record a destination reference only after the result is established. If a timeout leaves the outcome uncertain, reconcile by the operation reference before retrying a mutation. Do not assume a missing response means nothing happened.

The local simulator below accepts an example event ID once and ignores the same ID on repeat. It is deliberately limited to memory in one page. Reloading clears it, and it does not model concurrent workers. Use it to understand the behavior, then implement durable guarantees in the actual backend.

4. Separate retryable and permanent failures

Classify failures using the destination’s documented behavior. A temporary unavailable response may justify bounded retry with delay and jitter. Invalid required data usually needs correction rather than repeated identical requests. Rate limits require honoring the provider’s guidance, including Retry-After when supplied and applicable.

Set a maximum attempt count or retry horizon and record the next attempt time. Avoid tight loops that consume quotas and repeat the same failure. A financial or otherwise sensitive operation may need a stricter reconciliation path than a read-only sync. The policy should follow the operation’s consequences, not a generic retry template.

Worked example — illustrative or dated as stated

Illustrative sequence: event demo-001 is accepted and creates one destination effect. The same event is delivered again and creates none. Event demo-002 is a different operation and creates a second effect. A page reload clears the teaching simulator, demonstrating why browser memory is insufficient for production duplicate protection.

5. Create a visible failure queue

After retries are exhausted or a permanent error occurs, preserve a safe diagnostic record and route it to an owner. Include operation reference, stage, error category, time and recovery action. Avoid storing full sensitive payloads merely because they make debugging convenient. Redact secrets and personal details from logs.

An alert is useful only if someone can act on it. Write the recovery procedure: verify whether the destination already has the record, correct invalid data if authorized, then replay the original operation reference. A new arbitrary ID can defeat duplicate protection and create the second record you were trying to avoid.

6. Run the handoff test matrix

Test a valid event, duplicate event, invalid payload, temporary failure, timeout after acceptance, exhausted retries and recovery. Confirm the destination effect and the safe audit record. Use fictional data and an isolated environment so the test does not notify real customers or create billable actions.

Record expected and actual results. The handoff is ready when repeated delivery creates one intended effect, failures are visible and the owner can recover without guessing. Keep the specification next to the implementation and rerun relevant cases after changing the source, destination or automation platform.

Copyable implementation example

Adapt this example to your actual environment and verify its assumptions before use.

event_id: demo-001
event_type: lead.accepted
version: 1
lead_ref: fictional-001
# Example contract only; no customer data or credentials.

Sources and scope

Primary-source guidance checked October 27, 2026. Interfaces and policies can change; consult the linked current source. Practice screenshots and modeled examples are labeled and are not client campaign results.

• Stripe fulfillment and repeated calls
• Lead acceptance measurement

Your next step

Continue with the related implementation lesson →