Choose an Idempotency Key for Internal CRM Tasks
Compare six synthetic collisions across event, target, operation, environment and payload revision before implementing duplicate controls.
10/24/20263 min read
An idempotency key should identify the intended business operation, not merely the moment a worker happened to run. If the key changes on every retry, it cannot help recognize repeated attempts. If it is too broad, it can incorrectly collapse two legitimate tasks into one.
Design the identity contract before choosing a hash function or adding a connector option. A key is not an authorization token, and a local ledger does not automatically guarantee exactly-once behavior at the destination. The provider's actual API contract and the application's concurrency controls still matter.
Specify the operation's identity
For a fictional internal CRM task, define the identity bundle as environment, tenant, source event ID, target record ID and operation type. Keep an approved payload revision and payload digest alongside the key. This proposed design treats a changed payload for the same operation as a review conflict, not an automatic new task.
An administrator may choose a different contract where a new approved revision represents a genuinely new business operation. That choice must be explicit. Simply appending the current timestamp or a random run ID makes every retry look new; silently appending a changed payload can bypass the intended duplicate check.
A six-collision specification
The synthetic baseline is production tenant T1, event E204, account A18, operation create-internal-review-task, approved payload revision P3. Its ledger state is completed, with destination task reference D77. Use these six cases to test the identity design without writing to a real CRM.
K1: same bundle and P3 arrive again after a response timeout. Expected: recognize the same operation; reconcile D77; no new task.
K2: same event E204 but target A81. Expected: different identity, yet hold because target scope differs from the original approval; a unique key is not permission.
K3: same target and event but operation update-review-note. Expected: distinct operation type; require its own applicable authorization.
K4: same bundle but payload revision P4 changes the requested review. Expected: payload conflict; do not overwrite P3 or create a new task automatically.
K5: event E205 independently requests a later review for A18. Expected: distinct business operation if genuinely authorized, even when wording matches P3.
K6: identical IDs in a test environment or another tenant. Expected: separate namespace; never collide with production T1.
The artifact records each input bundle, expected key relationship, approval state, prior outcome and permitted disposition. Include a case where two workers receive K1 simultaneously. A check followed by an unprotected insert can race; the engineering design needs an atomic claim or equivalent supported concurrency control, not just a polite instruction to avoid duplicates.
Keep payload comparison explicit
Decide which fields affect operation meaning and how their representation is normalized. Differences in insignificant spacing may be irrelevant; changes to target, owner, deadline or requested action can be material. Use a documented canonical representation appropriate to the system, and test that it does not erase meaningful distinctions.
Do not store full contact payloads in the key or expose them in logs. A digest can support comparison, but it does not establish confidentiality, integrity or authorization by itself. Security owners should review the implementation and retention of the ledger.
Respect the destination contract
Some APIs offer documented idempotency support; others do not. Do not invent a header or assume a workflow engine deduplicates every operation. n8n documents error workflows for failed executions. An error workflow is not evidence that a remote task was undone or that a repeated request is safe.
If the destination outcome is uncertain, inspect the supported operation reference or route to reconciliation before retrying. Define how long duplicate evidence remains available and what happens after the provider or local ledger's retention window. Expired evidence should not silently become permission to repeat.
The completed key specification should explain which events represent the same operation, which differences require review and how concurrent arrivals are handled. Test those decisions with synthetic collisions before relying on the design for shared records.
If you are also choosing research access, ask about Leads Automation’s independent Sales Navigator offer at US$15/month on WhatsApp. Confirm the available plan, eligibility and terms before ordering; Leads Automation is not affiliated with LinkedIn. This is not LinkedIn’s official price or an assurance that any particular integration is included.