Kafka Events

Event-driven integration guide for the Marketplace Service

Overview

The Marketplace Service uses Apache Kafka (Amazon MSK Serverless) for asynchronous event-driven communication. All events follow the CloudEvents 1.0 specification with tenant_id as the partition key for data isolation.

Kafka on Lambda

Kafka producers are enabled via the KAFKA_ENABLED environment variable. On Lambda, this is set to false by default — events are silently skipped. Enable Kafka when the service is connected to the VPC with MSK access.

Broker

boot-gpm4u49z.c2.kafka-serverless.us-east-1.amazonaws.com:9098

CloudEvents Envelope

{
  "specversion": "1.0",
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "eventzr.marketplace.listing.created.v1",
  "source": "marketplace-svc",
  "time": "2026-03-02T12:00:00.000Z",
  "datacontenttype": "application/json",
  "subject": "listing:uuid",
  "tenantid": "00000000-0000-0000-0000-000000000001",
  "data": {
    "id": "listing-uuid",
    "title": "Premium Catering Service",
    "lane": "vendora",
    "sellerId": "seller-uuid",
    "price": 5000,
    "currency": "USD"
  }
}

Producer Topics (12)

Events published by marketplace-svc:

Topic	Description	Payload
`eventzr.marketplace.listing.created.v1`	Emitted when a new marketplace listing is created	Listing entity with seller info, lane, pricing
`eventzr.marketplace.listing.published.v1`	Emitted when a listing transitions to published state	Listing ID, seller ID, lane, publish timestamp
`eventzr.marketplace.listing.updated.v1`	Emitted when listing details are modified	Updated listing fields (partial)
`eventzr.marketplace.listing.closed.v1`	Emitted when a listing is closed or deactivated	Listing ID, close reason, final statistics
`eventzr.marketplace.quote.submitted.v1`	Emitted when a buyer submits a quote on a listing	Quote entity with listing ID, amount, message
`eventzr.marketplace.quote.accepted.v1`	Emitted when a seller accepts a quote	Quote ID, listing ID, accepted amount
`eventzr.marketplace.order.created.v1`	Emitted when an order is created from an accepted quote	Order entity with quote reference, buyer/seller IDs
`eventzr.marketplace.order.completed.v1`	Emitted when an order is marked as completed	Order ID, completion timestamp, final amount
`eventzr.marketplace.order.cancelled.v1`	Emitted when an order is cancelled	Order ID, cancellation reason, refund status
`eventzr.marketplace.dispute.opened.v1`	Emitted when a dispute is opened on an order	Dispute entity with order reference, reason, evidence
`eventzr.marketplace.dispute.resolved.v1`	Emitted when a dispute is resolved by admin	Dispute ID, resolution outcome, notes
`eventzr.marketplace.rfp.broadcast.v1`	Emitted when an RFP is broadcast to matching sellers	RFP entity with requirements, target lanes, deadline

Consumer Topics (6)

Events consumed by marketplace-svc from other services:

Topic	Source	Description
`eventzr.event.created.v1`	event-svc	Consumes event creation events to auto-create marketplace context (exhibitor slots, sponsorship opportunities)
`eventzr.reviews.review.created.v1`	reviews-svc	Consumes review events to update seller ratings and listing quality scores
`eventzr.wallet.payment.completed.v1`	wallet-svc	Consumes payment completion events to transition orders to paid status
`eventzr.wallet.escrow.released.v1`	wallet-svc	Consumes escrow release events to complete seller payouts on order delivery
`eventzr.subscriptions.subscription.changed.v1`	subscriptions-svc	Consumes subscription change events to update seller tier entitlements and listing limits
`eventzr.user.profile.updated.v1`	user-svc	Consumes profile update events to sync seller display info across listings

Integration Example

Subscribe to marketplace events using @eventzr/kafka:

import { KafkaConsumer, OnMessage } from '@eventzr/kafka';

@KafkaConsumer({ groupId: 'your-service-marketplace-consumer' })
export class MarketplaceEventHandler {
  @OnMessage('eventzr.marketplace.listing.created.v1')
  async handleListingCreated(event: CloudEvent) {
    const { tenantid, data } = event;
    // Process the new listing in your service context
    console.log(`New listing in lane ${data.lane}: ${data.title}`);
  }

  @OnMessage('eventzr.marketplace.order.completed.v1')
  async handleOrderCompleted(event: CloudEvent) {
    const { data } = event;
    // Trigger post-order workflows (review request, analytics, etc.)
    console.log(`Order ${data.id} completed`);
  }
}