Understand why Cotonity agents sometimes create duplicate CRM records and apply deduplication strategies including upsert operations, idempotency keys, and pre-run existence checks.
Why duplicates occur
Duplicate records typically arise from one of three situations: a workflow is triggered multiple times for the same event (for example, a webhook fires twice because the sending system retried a request it thought had failed), a workflow creates a record before checking whether one already exists, or two separate workflows both create records in response to related but distinct events. The first step in diagnosing duplication is to open the Activity log and count how many runs occurred for the affected time period. If multiple runs fired for what should have been a single event, the trigger is firing more than once and you need to address the source of the duplicate events.
Using upsert instead of create
The most reliable way to prevent duplicates is to replace 'Create record' steps with 'Upsert record' steps. An upsert operation creates a new record only if no existing record matches the specified deduplication key — otherwise it updates the existing record. In the CRM step editor, switch the operation type from 'Create' to 'Upsert' and select the deduplication field, typically email address for contacts or domain for companies. The upsert operation is idempotent: running it multiple times with the same input produces the same result, so even if a workflow fires twice, only one record will exist afterward.
Adding pre-run existence checks
For scenarios where an upsert is not available — such as creating records in a system that does not support it — add a 'Search records' step before the create step. Configure the search step to look for an existing record using the same deduplication key you would use for an upsert. Connect the search result to a conditional step: if a matching record is found, branch to an 'Update record' step; if no match is found, branch to the 'Create record' step. This pattern effectively implements upsert logic for any system. The tradeoff is that it requires two API calls instead of one, so it is slightly slower and more complex to maintain.
Idempotency keys for webhook triggers
If duplicates are caused by retry logic in the upstream system sending the same webhook event multiple times, configure idempotency keys on the Cotonity webhook trigger. An idempotency key is a unique identifier included in the webhook payload — for example, a transaction ID or event ID from the sending system. When enabled, Cotonity tracks received idempotency keys and discards any webhook request whose key matches a recently processed request. To enable this, open the trigger settings, navigate to the Idempotency section, and specify the payload field that contains the unique key. The deduplication window is configurable from one hour up to seven days.