Idempotency in Dynamics 365 integrations

In any distributed system, messages can be delivered more than once. A network timeout, a webhook retry, a Service Bus redelivery — all produce the same business event arriving twice. An integration that's not idempotent processes the message twice, creating duplicate records, double-charging customers, or sending repeated notifications. Designing for idempotency from the start is fundamental.

The problem.

A naive integration:

1. External system sends "Customer X placed Order Y" event.
2. Network glitch; the publisher retries.
3. The consumer receives the event twice.
4. The consumer creates Order Y twice in Dataverse.
5. Customer X has two orders for one purchase; chaos.

Idempotency means: running the same operation twice produces the same result as running it once.

Patterns for idempotent operations.

1. Check before create. Before inserting a record, query for it:

Does Order Y exist?
  Yes → already processed; do nothing.
  No → create Order Y.

This works but has a race condition: two simultaneous executions could both find "doesn't exist" and both insert. Acceptable for low-volume scenarios with reasonable network conditions; insufficient for high-volume / mission-critical.

2. Upsert with alternate key. Use Dataverse's Upsert operation with an alternate key:

PATCH /api/data/v9.2/salesorders(ordernumber='Y')
{ ...order data... }

If the order exists, it's updated; if not, it's created. The platform handles the atomicity. Idempotent by design.

3. Correlation ID. Each external event carries a unique identifier (the event's ID, a UUID, a deduplication token). The consumer:

1. Receives the event with correlation ID evt-123.
2. Checks "have I processed event evt-123 before?" against a tracking store (Dataverse table, Azure Cache, or message header).
3. If yes, skip.
4. If no, process and record evt-123 as processed.

This handles cases where the business operation isn't naturally identifiable by a stable business key.

4. Idempotency tokens. Some patterns send an explicit idempotency token in the request header. The consumer treats requests with the same token as duplicates of each other.

5. Natural keys. Many business entities have natural keys — order number, invoice number, transaction reference. If the publisher uses these consistently and the consumer matches by them, duplicates are detected naturally.

Dataverse-specific patterns.

Upsert. As mentioned, Dataverse's Upsert is the canonical pattern:

PATCH /api/data/v9.2/salesorders(ordernumber='ORD-2026-001')
Headers: If-Match: *
{
  "orderdate": "2026-01-15",
  "customerid_account@odata.bind": "/accounts(<GUID>)",
  ...
}

With an alternate key on ordernumber, the operation is idempotent regardless of how many times it's called with the same data.

ETag-based concurrency. Beyond idempotency, ETag-based optimistic concurrency prevents lost updates:

• Read the record; get its ETag.
• Submit the update with If-Match: <etag>.
• If the record changed between read and write, the update fails; consumer re-reads and retries.

Different from idempotency but complementary.

Service Bus deduplication. Azure Service Bus supports message deduplication — messages with the same MessageId within a deduplication window are treated as duplicates and discarded automatically. Set the MessageId to the business event's correlation ID; Service Bus handles the deduplication infrastructure.

Webhooks. Dataverse webhooks include a Cloud Event ID header — a unique ID per event firing. Consumers track which IDs have been processed; duplicates are detected.

Power Automate flows.

• Native trigger deduplication isn't always supported; check per trigger.
• Explicit deduplication step — use a Dataverse table to track processed correlation IDs; the flow checks before processing.
• Idempotent action choice — prefer Upsert over Create when possible.

Plug-ins.

Synchronous plug-ins running in the originating transaction inherit transactional idempotency — if the transaction fails, all effects roll back, including the plug-in's. Asynchronous plug-ins may retry; design them as idempotent or accept duplicates.

Compensation actions. When idempotency isn't possible (e.g. notification sending, payment processing), use compensation:

• Track every action with status.
• On detection of duplicate processing, compensate (reverse the duplicate effect).

Compensation is complex; design carefully.

Why this matters.

• Distributed systems aren't reliable — messages duplicate. Idempotency is the only sane design pattern.
• Retries are inevitable — clients retry on timeouts; queues redeliver; webhooks retry.
• Without idempotency, every retry is a bug waiting to happen.

Common pitfalls.

• Assuming "won't happen" — duplicates happen far more often than developers expect.
• No correlation ID — can't detect duplicates after the fact.
• Check-before-create with race conditions — works at low volume; fails at scale.
• Side effects without idempotency consideration — duplicate notifications, double-charges, repeated webhooks downstream.

Operational reality. Design every Dynamics 365 integration as idempotent. The investment is small; the cost of not doing it is dramatic when problems occur. Use Upsert, use correlation IDs, use natural keys; track processed events; expect retries.