Event-Driven CRM–ERP Integration | Webhooks, Idempotency, Outbox

Why polling fails for CRM–ERP integrations

Polling looks simple: “every 5 minutes, fetch changes.” In production, it usually becomes a reliability tax: higher API costs, long windows of stale data, and complex edge cases when records change multiple times between polls. If your CRM is driving quote-to-cash, or your ERP is driving inventory and fulfillment, stale state becomes operational risk.

Webhooks are at-least-once: design for duplicates

The critical nuance in webhook delivery is “at-least-once.” Providers retry when they see timeouts, 5xx responses, network failures, or rate limiting. That’s good (you don’t lose events), but it also guarantees duplicates over time. Your handler must be safe when the same payload arrives multiple times.

Minimum viable webhook hardening

For your API layer, align your conventions with your existing integration guidance on /api-integrations (signature verification, idempotency keys, request validation, and observability baselines).

Idempotency keys: the contract that prevents double writes

Idempotency means: “processing the same event twice produces the same final state as processing it once.” In a webhook-based CRM↔ERP integration, this is non-negotiable because retries and duplicates are part of normal operations.

idempotency_key = "{provider}:{event_id}"

idempotency_key = sha256(
  provider + ":" +
  event_type + ":" +
  entity_id + ":" +
  entity_version_or_updated_at
)

Idempotent handler: the practical flow

1. 1

   Verify signature and timestamp. Reject unauthenticated traffic early.

2. 2

   Upsert idempotency record with a unique constraint. If it already exists, return 200/202 and stop.

3. 3

   Enqueue the work (queue topic per domain: orders, shipments, returns, invoices).

4. 4

   Process in workers with retries + DLQ, version checks, and structured logs.

The Outbox pattern: eliminate “DB updated but event lost” drift

The Outbox pattern is the pragmatic alternative to brittle “publish then commit” flows. The core promise: your business write and the event record are saved in the same database transaction. If the app crashes after committing, the event is still there and can be published later. No drift.

Outbox table: pragmatic fields

outbox_events
- id (uuid / bigserial)
- aggregate_type (e.g., "order", "shipment", "return")
- aggregate_id (string/uuid)
- event_type (e.g., "order.created", "return.approved")
- payload_json (jsonb)
- correlation_id (string)
- idempotency_key (string, optional)
- status ("pending" | "published" | "failed")
- attempts (int)
- next_attempt_at (timestamp)
- published_at (timestamp, nullable)
- created_at (timestamp)

When your integration touches business workflows like Returns & Claims, you want the Outbox pattern to ensure the “return approved → ERP credit note created” chain never silently breaks. See: /returns-and-claims.

Retry/DLQ strategy: turn failures into managed work

Mature integrations don’t “avoid failures.” They operationalize them: retries for transient issues, DLQ for poison messages, and dashboards that make replay safe.

Ordering guarantees: the silent source of “random” bugs

Even if webhooks arrive reliably, you cannot assume ordering. Two updates for the same order can arrive out of order, or be processed concurrently by different workers. If you ignore this, you’ll get intermittent regressions like: “status went from Shipped back to Approved.”

Practical rollout: from fragile to production-grade in phases

Don’t big-bang “event-driven everything.” Roll out by business impact and operational risk. Start with one or two high-value streams (orders and returns are typically the fastest wins), harden the platform, then expand.

FAQ