Skip to main content

Eventing & Integration

The platform is event-driven: Medusa and the NestJS domains stay coherent by exchanging domain events, not by sharing tables. This is the seam that makes the polyglot split safe.

The event bridge​

  • Outbox pattern: the producer writes the business change and the event row in the same transaction, so an event is never lost if the write commits. A relay ships outbox rows to BullMQ.
  • BullMQ on Redis is the transport (queues, retries, delays, DLQ).
  • Idempotent consumers: every handler dedupes on eventId and is safe to retry.
  • Dead-letter queue: poison messages park in a DLQ with alerting.

Canonical event catalog (initial)​

EventEmitted byConsumed byEffect
customer.createdMedusaCRMcreate/refresh 360 profile
order.placedMedusaLoyalty, CRM, Automationaccrue points (pending), lead/automation triggers
order.deliveredMedusaWarranty, FSMmark warranty-eligible; offer installation
serial.assignedMedusa/InventoryWarrantyregister serial → asset (unregistered)
warranty.registeredWarrantyCRM, Notifications, Loyaltyconfirm; bonus points
installation.completedFSMNotifications (delayed 7d), Loyalty, Warrantyschedule testimonial request; activate warranty start
ticket.createdFSMNotifications, Automationacknowledge customer; webhook out
ticket.closedFSMCRM, Notifications, BICSAT request; metrics
amc.due_soonFSM (scheduler)Notificationsrenewal reminder
claim.approvedWarrantyFSM, Financecreate repair/replace job; cost recovery
payment.capturedMedusa/HyperswitchFinance, Loyaltyreconcile; confirm points
dealer.target.updatedDMSNotifications, BInotify dealer; refresh dashboards

Events are versioned (v1, v2) and documented in API Surface. Payloads carry IDs + a minimal snapshot; consumers fetch more via the BFF if needed.

The 7-day testimonial flow (worked example)​

A delayed BullMQ job (not a cron scan) is scheduled when installation completes; on fire it re-checks validity (e.g. no open complaint) before asking. See Marketing & Content module.

Inbound integrations​

SourceMechanismLands as
Hyperswitchwebhook → BFFpayment.* events
Shiprocketwebhook → BFFshipment.* → updates Medusa fulfillment
Amazon/Flipkartscheduled pull + webhookchannel order/inventory sync (see Marketplaces)

Outbound automation — n8n, Zapier & Pabbly​

The platform exposes selected domain events to automation engines so the business can wire workflows (e.g. "complaint → auto-assign technician via n8n", "new high-value order → Slack", "AMC due → WhatsApp via Pabbly"). n8n (self-hosted, in-cluster) is the primary internal engine; Zapier/Pabbly cover SaaS no-code.

  • An Automation dispatcher subscribes to whitelisted events and POSTs signed webhooks (HMAC with N8N_WEBHOOK_SECRET / ZAPIER_WEBHOOK_SECRET / PABBLY_WEBHOOK_SECRET) to configured endpoints.
  • Subscriptions (event → engine + URL) are tenant config, managed in admin.
  • Full contract, payloads, retries, and the n8n recipe catalog: Automation: n8n, Zapier & Pabbly.

Reliability rules​

  1. Outbox on every producer; never emit from application memory only.
  2. Idempotent consumers, keyed on eventId.
  3. Retries with backoff, then DLQ + alert.
  4. Versioned event schemas; additive changes preferred.
  5. Webhooks (in and out) are signed and verified.

Operating this in production — delivery guarantees, crash behaviour per component, scaling knobs, Redis HA, DLQ replay, and the env reference: see the Eventing Reliability & Operations Runbook.