How to Design an Integration Monitoring System

Integrations fail quietly. A web application that breaks gets user complaints within minutes; an integration that stops syncing can run for days before someone notices that orders are missing. Monitoring is how you shorten that gap from days to minutes. This guide describes what to measure and when to wake someone up.

Monitor three layers

1. Infrastructure

Is the integration running and able to reach its dependencies?

• Process or function health, restarts, memory, CPU.
• Database availability and connection pool saturation.
• Reachability and latency of the ecommerce API and the ERP API (synthetic checks every few minutes).
• Certificate expiry for webhook endpoints and ERP connections.
• Credential validity (a scheduled call that fails loudly on 401/403).

Infrastructure monitoring is necessary but insufficient: a perfectly healthy service can still be processing nothing.

2. Pipeline

Is work flowing through the integration?

Metric	Why it matters
Events received per workflow per interval	Detects missing inbound traffic
Jobs completed per interval	Detects stalled workers
Queue depth (pending + retrying)	Detects backlogs
Age of oldest pending job	Best single indicator of business delay
Failure rate per workflow	Detects new errors and regressions
Items in review and dead-letter queues, and their age	Detects neglected failures
End-to-end latency (event time → ERP write)	Measures freshness against your requirement
API throttling events	Early warning of rate-limit pressure

3. Business outcome

Is the data actually correct? These checks catch problems pipeline metrics miss — a mapping bug that “succeeds” with wrong values, or orders that never generated an event.

• Order completeness: every order created in the store during a window has a linked ERP order (excluding documented exclusions).
• Order value match: daily totals per currency match between the store and the ERP within tolerance.
• Inventory drift: number and percentage of SKUs whose published quantity differs from the ERP-derived sellable quantity.
• Fulfillment lag: orders shipped in the ERP but still unfulfilled in the store after a threshold.
• Refund match: refund totals per day match credit note totals.

Run these as scheduled reconciliation jobs and store the results as metrics.

Alerting: page only for actionable symptoms

A good alert describes a condition a human must act on within a known time. Suggested starting points — tune them to your volume and service levels:

Alert	Example condition	Urgency
Pipeline stalled	Oldest pending order job older than 30 minutes	High
Expected traffic missing	No new orders received for 60 minutes during hours when orders normally arrive	High
ERP unreachable	Synthetic check failing for 10 minutes	High
Credentials invalid	Any 401/403 from platform or ERP	High
Review queue neglected	Oldest review item older than 4 business hours	Medium
Dead-letter arrival	Any new item	Medium (developer hours)
Failure rate spike	Failure rate more than 3× its 7-day baseline	Medium
Reconciliation mismatch	Missing orders > 0, or inventory drift above threshold	Medium
Webhook delivery degradation	Platform-reported failures or slow responses	Medium

Shopify’s webhook troubleshooting guide, for example, flags failure rates above 0.5% and response times between four and five seconds as symptoms to address — useful thresholds if you receive Shopify webhooks.

Reduce noise

• Deduplicate and group: an ERP outage should produce one alert (“ERP unreachable”) rather than one per failed job.
• Suppress downstream alerts while an upstream alert is active.
• Use business hours for medium-urgency alerts.
• Review alerts monthly: delete any that fired without leading to an action.

Trace any record end to end

Support’s most common question is “what happened to order #1042?” Make that answerable in one search:

• Assign a correlation ID when an event enters the integration and include it in every log line, job record, and outbound request header.
• Log key transitions at info level: received, fetched, mapped, written, linked, with the ecommerce ID and ERP document number.
• Store the link table (ecommerce ID ↔ ERP ID) permanently.
• If you use distributed tracing (for example OpenTelemetry), propagate trace context through the queue so one trace spans webhook to ERP call.

Dashboards

Two dashboards serve different audiences:

Operations dashboard (business language):

• Orders received today / exported / in review / failed.
• Orders older than 30 minutes not yet in the ERP, with links.
• Shipments not yet reflected in the store.
• Last successful inventory sync and current drift.

Engineering dashboard:

• Throughput, queue depth, oldest-job age per workflow.
• Error rates by category and error type.
• API latency and throttling for each external system.
• Deployments overlaid on charts, to correlate regressions.

Implementing with minimal tooling

Without a dedicated observability stack, you can still do this well:

-- Run every minute; write results to a metrics table or push to your alerting tool.
SELECT
  topic,
  count(*) FILTER (WHERE status IN ('pending','failed'))         AS backlog,
  extract(epoch FROM now() - min(created_at)
          FILTER (WHERE status IN ('pending','failed')))         AS oldest_pending_seconds,
  count(*) FILTER (WHERE status = 'review')                      AS in_review,
  count(*) FILTER (WHERE status = 'dead')                        AS dead_lettered
FROM inbound_events
WHERE created_at > now() - interval '7 days'
GROUP BY topic;

Pair it with a scheduler, a small script that compares values to thresholds, and a notification channel. Move to a full observability platform when volume or team size justifies it.

Security and privacy

• Logs and traces often capture personal data. Redact addresses, emails, and phone numbers, or keep them out of logs entirely and refer to records by ID.
• Restrict dashboard access by role.
• Treat alert messages as potentially visible to many people; do not include secrets or full payloads.

Testing your monitoring

Monitoring that has never fired is unproven:

• Stop the worker in staging and confirm the stalled-pipeline alert fires within its window.
• Revoke a test credential and confirm the auth alert fires.
• Insert a fake order with no ERP link and confirm reconciliation reports it.
• Run a game day: simulate an ERP outage for an hour and walk through the response.

Common mistakes

• Monitoring only infrastructure health.
• Alerting on every individual failure.
• No “expected traffic” check, so a removed webhook subscription goes unnoticed.
• No end-to-end correlation ID.
• Reconciliation results nobody reviews.

Summary

Monitor infrastructure, pipeline flow, and business outcomes. Treat the age of the oldest pending item as a primary metric, alert only on actionable symptoms, and use reconciliation to verify that data is complete and correct, not just processed. Correlation IDs and a permanent link table make every order traceable, which is what support and operations need most.