@freighttech/shipment-tracking 0.6.0

package/src/modules/shipment_tracking/services/webhookService.ts

@@ -0,0 +1,347 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { EventBus } from '@open-mercato/events'
+import { findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { Shipment, TrackingEvent, TrackingJob, Webhook, WebhookDelivery } from '../data/entities'
+import { dispatchWebhook } from '../lib/webhook-dispatcher'
+import { sleep } from '../lib/background'
+
+type WebhookServiceDeps = {
+  em: () => EntityManager
+  eventBus: EventBus
+}
+
+const RETRY_DELAYS_MS = [5_000, 30_000, 120_000] // 5s, 30s, 2min
+const MAX_RETRIES = 3
+
+/**
+ * Builds a full shipment payload including tracking events for webhook dispatch.
+ * Includes all DCSA T&T v3.0 fields.
+ * Timestamps are provided as multi-source arrays; consumers compute primary via "latest updatedAt wins".
+ */
+function buildShipmentPayload(shipment: Shipment, trackingEvents: TrackingEvent[]): Record<string, unknown> {
+  // Get current location from latest tracking event (derived at query time)
+  const latestEvent = trackingEvents.length > 0 ? trackingEvents[trackingEvents.length - 1] : null
+
+  return {
+    id: shipment.id,
+    status: shipment.status,
+    carrierCode: shipment.carrierCode,
+    containerNumber: shipment.containerNumber,
+    isoEquipmentCode: shipment.isoEquipmentCode,
+    bookingNumber: shipment.bookingNumber,
+    bolNumber: shipment.bolNumber,
+    // Multi-source timestamp arrays (consumers compute primary via "latest updatedAt wins")
+    etdTimestamps: shipment.etdTimestamps,
+    etaTimestamps: shipment.etaTimestamps,
+    atdTimestamps: shipment.atdTimestamps,
+    ataTimestamps: shipment.ataTimestamps,
+    // Origin/destination (rich JSONB location data)
+    originLocation: shipment.originLocation,
+    destinationLocation: shipment.destinationLocation,
+    // Current location derived from latest event
+    currentLocationName: latestEvent?.locationName ?? null,
+    currentLocationUnlocode: latestEvent?.locationUnlocode ?? null,
+    // Vessel info
+    vesselName: shipment.vesselName,
+    vesselImo: shipment.vesselImo,
+    voyageNumber: shipment.voyageNumber,
+    eventCount: shipment.eventCount,
+    lastEventAt: shipment.lastEventAt?.toISOString() ?? null,
+    extra: shipment.extra,
+    createdAt: shipment.createdAt?.toISOString() ?? null,
+    updatedAt: shipment.updatedAt?.toISOString() ?? null,
+    trackingEvents: trackingEvents.map((event) => ({
+      // Event source
+      id: event.id,
+      source: event.source,
+      sourceEventId: event.sourceEventId,
+
+      // Core event fields
+      eventType: event.eventType,
+      eventCode: event.eventCode,
+      eventClassifierCode: event.eventClassifierCode,
+      eventDateTime: event.eventDateTime?.toISOString() ?? null,
+      eventDateTimeOffset: event.eventDateTimeOffset,
+      description: event.description,
+
+      // Equipment fields (DCSA EQUIPMENT events)
+      equipmentReference: event.equipmentReference,
+      isoEquipmentCode: event.isoEquipmentCode,
+      emptyIndicatorCode: event.emptyIndicatorCode,
+      isTransshipmentMove: event.isTransshipmentMove,
+
+      // Location fields
+      locationName: event.locationName,
+      locationUnlocode: event.locationUnlocode,
+      locationCountry: event.locationCountry,
+      facilityCode: event.facilityCode,
+      facilityCodeListProvider: event.facilityCodeListProvider,
+      facilityTypeCode: event.facilityTypeCode,
+      latitude: event.latitude,
+      longitude: event.longitude,
+
+      // Transport call fields
+      transportCallReference: event.transportCallReference,
+      modeOfTransport: event.modeOfTransport,
+      vesselName: event.vesselName,
+      vesselImo: event.vesselImo,
+      voyageNumber: event.voyageNumber,
+      carrierServiceCode: event.carrierServiceCode,
+      carrierExportVoyageNumber: event.carrierExportVoyageNumber,
+      carrierImportVoyageNumber: event.carrierImportVoyageNumber,
+      universalServiceReference: event.universalServiceReference,
+      universalExportVoyageReference: event.universalExportVoyageReference,
+      universalImportVoyageReference: event.universalImportVoyageReference,
+      portVisitReference: event.portVisitReference,
+
+      // Document references
+      relatedDocumentReferences: event.relatedDocumentReferences,
+
+      // Metadata fields
+      eventCreatedDateTime: event.eventCreatedDateTime?.toISOString() ?? null,
+      retractedEventId: event.retractedEventId,
+      publisherName: event.publisherName,
+      publisherRole: event.publisherRole,
+
+      // Additional fields
+      delayReasonCode: event.delayReasonCode,
+      changeRemark: event.changeRemark,
+      seals: event.seals,
+
+      // Timestamps
+      createdAt: event.createdAt?.toISOString() ?? null,
+    })),
+  }
+}
+
+/**
+ * WebhookService handles finding matching webhooks and dispatching them
+ * with full shipment data and retry logic.
+ */
+export class WebhookService {
+  private deps: WebhookServiceDeps
+
+  constructor(deps: WebhookServiceDeps) {
+    this.deps = deps
+  }
+
+  /**
+   * Builds the full shipment payload including tracking events.
+   * Events are fetched from the TrackingJob associated with the shipment.
+   */
+  async buildFullShipmentPayload(shipmentId: string): Promise<Record<string, unknown> | null> {
+    const em = this.deps.em()
+
+    const shipment = await em.findOne(Shipment, { id: shipmentId, deletedAt: null }, { populate: ['trackingJob'] })
+    if (!shipment) {
+      return null
+    }
+
+    // If shipment has a tracking job, get events filtered for this container
+    let trackingEvents: TrackingEvent[] = []
+    if (shipment.trackingJob) {
+      const allEvents = await em.find(
+        TrackingEvent,
+        { trackingJob: shipment.trackingJob },
+        { orderBy: { eventDateTime: 'asc' } },
+      )
+      // Filter events for this specific container
+      // Include TRANSPORT events (no equipmentReference) and EQUIPMENT events matching this container
+      trackingEvents = allEvents.filter((event) => {
+        if (event.eventType === 'TRANSPORT') return true
+        if (event.eventType === 'EQUIPMENT') {
+          return event.equipmentReference === shipment.containerNumber
+        }
+        return false
+      })
+    }
+
+    return buildShipmentPayload(shipment, trackingEvents)
+  }
+
+  /**
+   * Dispatches webhooks for a shipment event with full data and retry logic.
+   *
+   * @param input.eventType - The event type (e.g., 'shipment.created', 'shipment.tracking_update')
+   * @param input.shipmentPayload - Full shipment data including cargo events
+   * @param input.tenantId - Tenant ID for finding matching webhooks
+   * @param input.organizationId - Organization ID for finding matching webhooks
+   * @returns Number of webhooks successfully dispatched
+   */
+  async dispatchWithRetry(input: {
+    eventType: string
+    shipmentPayload: Record<string, unknown>
+    tenantId: string
+    organizationId: string
+  }): Promise<{ success: boolean; dispatched: number; failed: number }> {
+    const em = this.deps.em()
+
+    // Find matching webhooks
+    const webhooks = await findWithDecryption(
+      em,
+      Webhook,
+      {
+        tenantId: input.tenantId,
+        organizationId: input.organizationId,
+        isActive: true,
+      },
+      undefined,
+      { tenantId: input.tenantId, organizationId: input.organizationId },
+    )
+
+    // Filter to webhooks subscribed to this event type
+    const matching = webhooks.filter((webhook) => {
+      return webhook.eventsSubscribed.some((pattern) => {
+        // Exact match
+        if (pattern === input.eventType) return true
+        // Global wildcard
+        if (pattern === '*') return true
+        // Module wildcard (e.g., 'shipment_tracking.*' matches 'shipment_tracking.shipment.created')
+        if (pattern.endsWith('.*')) {
+          const prefix = pattern.slice(0, -2)
+          if (input.eventType.startsWith(prefix + '.')) return true
+        }
+        // Entity wildcard (e.g., 'shipment_tracking.shipment.*' matches 'shipment_tracking.shipment.created')
+        if (pattern.endsWith('.*')) {
+          const prefix = pattern.slice(0, -1)
+          if (input.eventType.startsWith(prefix)) return true
+        }
+        return false
+      })
+    })
+
+    if (matching.length === 0) {
+      console.debug('[shipment-tracking:webhook] No matching webhooks found for event:', input.eventType, {
+        totalWebhooks: webhooks.length,
+        webhookPatterns: webhooks.map((w) => w.eventsSubscribed),
+      })
+      return { success: true, dispatched: 0, failed: 0 }
+    }
+
+    console.log('[shipment-tracking:webhook] Dispatching to', matching.length, 'webhooks for event:', input.eventType)
+
+    let dispatched = 0
+    let failed = 0
+
+    const fullPayload = {
+      type: input.eventType,
+      timestamp: new Date().toISOString(),
+      ...input.shipmentPayload,
+    }
+
+    for (const webhook of matching) {
+      const result = await this.dispatchSingleWebhook(em, webhook, fullPayload, input.eventType)
+      if (result.success) {
+        dispatched++
+      } else {
+        failed++
+      }
+    }
+
+    return {
+      success: failed === 0,
+      dispatched,
+      failed,
+    }
+  }
+
+  /**
+   * Dispatches a single webhook with retry logic.
+   * Records delivery attempts in the WebhookDelivery table for audit.
+   */
+  private async dispatchSingleWebhook(
+    em: EntityManager,
+    webhook: Webhook,
+    payload: Record<string, unknown>,
+    eventType: string,
+  ): Promise<{ success: boolean }> {
+    // Create delivery record for audit
+    // Use getReference to create a managed reference since webhook may be detached after decryption
+    const delivery = em.create(WebhookDelivery, {
+      webhook: em.getReference(Webhook, webhook.id),
+      eventType,
+      status: 'pending',
+      payload,
+      retryCount: 0,
+    })
+    em.persist(delivery)
+    await em.flush()
+
+    let lastResult: Awaited<ReturnType<typeof dispatchWebhook>> | null = null
+
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+      lastResult = await dispatchWebhook({
+        url: webhook.url,
+        payload,
+        hmacSecret: webhook.hmacSecret,
+      })
+
+      if (lastResult.success) {
+        // Success - update delivery record
+        delivery.status = 'success'
+        delivery.responseStatus = lastResult.responseStatus ?? null
+        delivery.responseBody = lastResult.responseBody ?? null
+        delivery.retryCount = attempt
+        await em.flush()
+
+        // Emit success event for monitoring
+        await this.deps.eventBus.emit('shipment_tracking.webhook.delivery_success', {
+          deliveryId: delivery.id,
+          webhookId: webhook.id,
+          eventType,
+          responseStatus: lastResult.responseStatus,
+        })
+
+        return { success: true }
+      }
+
+      // Failed - update delivery record with error
+      delivery.responseStatus = lastResult.responseStatus ?? null
+      delivery.responseBody = lastResult.responseBody ?? null
+      delivery.errorMessage = lastResult.errorMessage ?? null
+      delivery.retryCount = attempt + 1
+
+      if (attempt < MAX_RETRIES) {
+        // Wait before retry
+        const delayMs = RETRY_DELAYS_MS[attempt] ?? RETRY_DELAYS_MS[RETRY_DELAYS_MS.length - 1]
+        await sleep(delayMs)
+      }
+    }
+
+    // All retries exhausted
+    delivery.status = 'failed'
+    await em.flush()
+
+    // Emit failure event for monitoring
+    await this.deps.eventBus.emit('shipment_tracking.webhook.delivery_failed', {
+      deliveryId: delivery.id,
+      webhookId: webhook.id,
+      eventType,
+      retryCount: delivery.retryCount,
+      lastError: lastResult?.errorMessage ?? 'Unknown error',
+    })
+
+    return { success: false }
+  }
+
+  /**
+   * Legacy method for backwards compatibility with existing subscribers.
+   * Finds matching webhooks and dispatches them (used by kept subscribers).
+   *
+   * @deprecated Use dispatchWithRetry() for new code
+   */
+  async dispatchEvent(input: {
+    eventType: string
+    payload: Record<string, unknown>
+    tenantId: string
+    organizationId: string
+  }): Promise<number> {
+    const result = await this.dispatchWithRetry({
+      eventType: input.eventType,
+      shipmentPayload: input.payload,
+      tenantId: input.tenantId,
+      organizationId: input.organizationId,
+    })
+    return result.dispatched
+  }
+}

package/src/modules/shipment_tracking/setup.ts

@@ -0,0 +1,99 @@
+import type { ModuleSetupConfig } from '@open-mercato/shared/modules/setup'
+
+type SchedulerServiceType = {
+  register: (registration: {
+    name: string
+    description?: string
+    scopeType: 'system' | 'organization' | 'tenant'
+    organizationId?: string
+    tenantId?: string
+    scheduleType: 'cron' | 'interval'
+    scheduleValue: string
+    timezone?: string
+    targetType: 'queue' | 'command'
+    targetQueue?: string
+    targetCommand?: string
+    targetPayload?: unknown
+    sourceType?: 'user' | 'module'
+    sourceModule?: string
+    isEnabled?: boolean
+  }) => Promise<void>
+}
+
+export const setup: ModuleSetupConfig = {
+  defaultRoleFeatures: {
+    admin: ['shipment_tracking.*'],
+    employee: [
+      'shipment_tracking.shipments.view',
+      'shipment_tracking.tracking_jobs.view',
+      'shipment_tracking.carrier_configs.view',
+      'shipment_tracking.shipsgo_config.view',
+      'shipment_tracking.webhooks.view',
+      'shipment_tracking.location_overrides.view',
+    ],
+  },
+
+  seedDefaults: async (ctx) => {
+    // Register scheduled jobs for this organization
+    // The scheduler service may not be available in all installations
+    try {
+      const schedulerService = ctx.container.resolve<SchedulerServiceType>('schedulerService')
+
+      // Register daily poll schedule
+      await schedulerService.register({
+        name: 'Daily Shipment Tracking Poll',
+        description:
+          'Polls all active tracking jobs for carrier updates every day at 6:00 AM UTC. You can change the schedule time in the scheduler settings.',
+        scopeType: 'organization',
+        tenantId: ctx.tenantId,
+        organizationId: ctx.organizationId,
+        scheduleType: 'cron',
+        scheduleValue: '0 6 * * *', // 6:00 AM UTC daily
+        timezone: 'UTC',
+        targetType: 'command',
+        targetCommand: 'shipment_tracking.tracking.poll_all',
+        targetPayload: {
+          tenantId: ctx.tenantId,
+          organizationId: ctx.organizationId,
+        },
+        sourceType: 'module',
+        sourceModule: 'shipment_tracking',
+        isEnabled: true,
+      })
+      console.log(
+        `[shipment-tracking] Registered daily poll schedule for org ${ctx.organizationId}`,
+      )
+
+      // Register PRE_ARRIVAL evaluation schedule
+      // Runs every 6 hours to check IN_TRANSIT shipments approaching destination
+      await schedulerService.register({
+        name: 'Pre-Arrival Status Evaluation',
+        description:
+          'Checks IN_TRANSIT shipments every 6 hours and upgrades them to PRE_ARRIVAL when ETA is within 7 days.',
+        scopeType: 'organization',
+        tenantId: ctx.tenantId,
+        organizationId: ctx.organizationId,
+        scheduleType: 'cron',
+        scheduleValue: '0 */6 * * *', // Every 6 hours
+        timezone: 'UTC',
+        targetType: 'command',
+        targetCommand: 'shipment_tracking.tracking.evaluate_pre_arrival',
+        targetPayload: {
+          tenantId: ctx.tenantId,
+          organizationId: ctx.organizationId,
+        },
+        sourceType: 'module',
+        sourceModule: 'shipment_tracking',
+        isEnabled: true,
+      })
+      console.log(
+        `[shipment-tracking] Registered pre-arrival evaluation schedule for org ${ctx.organizationId}`,
+      )
+    } catch (error) {
+      // Scheduler module may not be installed - this is fine
+      console.debug('[shipment-tracking] Scheduler service not available, skipping schedule registration')
+    }
+  },
+}
+
+export default setup

package/src/modules/shipment_tracking/subscribers/__tests__/terminal-event-ingest.test.ts

@@ -0,0 +1,141 @@
+import { describe, it, expect, vi } from 'vitest'
+import handle, { metadata } from '../terminal-event-ingest'
+
+const PAYLOAD = {
+  sourceEventId: 'bct:11341499051:DEPA',
+  eventType: 'TRANSPORT' as const,
+  eventCode: 'DEPA',
+  eventClassifierCode: 'ACT' as const,
+  eventDateTime: '2026-06-03T01:58:00.000Z',
+  containerNumber: 'GCXU5598460',
+  tenantId: 'ten-1',
+  organizationId: 'org-1',
+  unlocode: 'PLGDN',
+  facilityCode: 'GDNBCT',
+  facilityCodeListProvider: 'SMDG' as const,
+  vesselName: null,
+  voyageNumber: null,
+  modeOfTransport: 'VESSEL' as const,
+  seals: [{ number: 'CN7842852' }],
+  rawData: { 'Unit Nbr': 'GCXU5598460', Category: 'Import' },
+}
+
+const shipment = (id: string, jobId: string | null) => ({
+  id,
+  organizationId: 'org-1',
+  tenantId: 'ten-1',
+  trackingJob: jobId ? { id: jobId } : null,
+})
+
+function setup(opts: { shipments: unknown[]; existing?: unknown }) {
+  const fork = {
+    find: vi.fn(async () => opts.shipments),
+    findOne: vi.fn(async () => opts.existing ?? null),
+    persist: vi.fn(),
+    flush: vi.fn(async () => {}),
+  }
+  const em = { fork: () => fork }
+  const service = { refreshShipmentsFromEvents: vi.fn(async () => {}) }
+  const resolve = vi.fn((name: string) => (name === 'em' ? em : service))
+  return { fork, service, resolve, ctx: { resolve } as never }
+}
+
+describe('terminal-event-ingest bridge subscriber', () => {
+  it('reacts to the terminal_tracking event id (string coupling only)', () => {
+    expect(metadata.event).toBe('terminal_tracking.terminal_event.created')
+    expect(metadata.id).toBe('shipment_tracking:terminal-event-ingest')
+  })
+
+  it("ingests a source:'port' TrackingEvent onto a matching shipment and refreshes it", async () => {
+    const { fork, service, ctx } = setup({ shipments: [shipment('ship-1', 'job-1')] })
+
+    await handle(PAYLOAD, ctx)
+
+    expect(fork.persist).toHaveBeenCalledTimes(1)
+    const ev = fork.persist.mock.calls[0][0] as Record<string, unknown>
+    expect(ev.source).toBe('port')
+    expect(ev.sourceEventId).toBe('bct:11341499051:DEPA')
+    expect(ev.eventCode).toBe('DEPA')
+    expect(ev.eventType).toBe('TRANSPORT')
+    expect(ev.eventClassifierCode).toBe('ACT')
+    expect(ev.equipmentReference).toBe('GCXU5598460')
+    expect(ev.facilityCode).toBe('GDNBCT')
+    expect(ev.locationUnlocode).toBe('PLGDN')
+
+    expect(fork.flush).toHaveBeenCalledTimes(1)
+    expect(service.refreshShipmentsFromEvents).toHaveBeenCalledTimes(1)
+    const [, jobId, shipmentIds] = service.refreshShipmentsFromEvents.mock.calls[0]
+    expect(jobId).toBe('job-1')
+    expect(shipmentIds).toEqual(['ship-1'])
+  })
+
+  it('dedupes: skips when a port event with the same sourceEventId already exists', async () => {
+    const { fork, service, ctx } = setup({
+      shipments: [shipment('ship-1', 'job-1')],
+      existing: { id: 'already-there' },
+    })
+
+    await handle(PAYLOAD, ctx)
+
+    expect(fork.persist).not.toHaveBeenCalled()
+    expect(fork.flush).not.toHaveBeenCalled()
+    expect(service.refreshShipmentsFromEvents).not.toHaveBeenCalled()
+  })
+
+  it('no-ops when the matching shipment has no tracking job', async () => {
+    const { fork, service, ctx } = setup({ shipments: [shipment('ship-1', null)] })
+
+    await handle(PAYLOAD, ctx)
+
+    expect(fork.findOne).not.toHaveBeenCalled()
+    expect(fork.persist).not.toHaveBeenCalled()
+    expect(service.refreshShipmentsFromEvents).not.toHaveBeenCalled()
+  })
+
+  it('no-ops (and does no work) when no shipment matches the container', async () => {
+    const { fork, service, ctx } = setup({ shipments: [] })
+
+    await handle(PAYLOAD, ctx)
+
+    expect(fork.persist).not.toHaveBeenCalled()
+    expect(fork.flush).not.toHaveBeenCalled()
+    expect(service.refreshShipmentsFromEvents).not.toHaveBeenCalled()
+  })
+
+  it('refreshes a job once for multiple shipments sharing it', async () => {
+    const { fork, service, ctx } = setup({
+      shipments: [shipment('ship-1', 'job-1'), shipment('ship-2', 'job-1')],
+    })
+
+    await handle(PAYLOAD, ctx)
+
+    expect(fork.persist).toHaveBeenCalledTimes(2)
+    expect(service.refreshShipmentsFromEvents).toHaveBeenCalledTimes(1)
+    const [, jobId, shipmentIds] = service.refreshShipmentsFromEvents.mock.calls[0]
+    expect(jobId).toBe('job-1')
+    expect(shipmentIds).toEqual(['ship-1', 'ship-2'])
+  })
+
+  it('scopes the shipment match to active, non-delivered shipments (no historic override)', async () => {
+    // A returned container reuses its number across journeys; the bridge must
+    // not refresh a closed/delivered shipment from a prior journey.
+    const { fork, ctx } = setup({ shipments: [] })
+
+    await handle(PAYLOAD, ctx)
+
+    const where = fork.find.mock.calls[0][1] as Record<string, unknown>
+    expect(where.containerNumber).toBe('GCXU5598460')
+    expect(where.deletedAt).toBeNull()
+    expect(where.isActive).toBe(true)
+    expect(where.status).toEqual({ $nin: ['DELIVERED'] })
+  })
+
+  it('guards against a malformed payload (missing containerNumber/sourceEventId)', async () => {
+    const { resolve, ctx } = setup({ shipments: [] })
+
+    await handle({ ...PAYLOAD, containerNumber: '' }, ctx)
+    await handle({ ...PAYLOAD, sourceEventId: '' }, ctx)
+
+    expect(resolve).not.toHaveBeenCalled()
+  })
+})

package/src/modules/shipment_tracking/subscribers/cargo-event-created.ts

@@ -0,0 +1,115 @@
+import type { DocumentReference } from '../data/entities'
+
+export const metadata = {
+  event: 'shipment_tracking.tracking_event.created',
+  persistent: true,
+  id: 'shipment_tracking:tracking-event-created',
+}
+
+type TrackingEventCreatedPayload = {
+  id: string
+  trackingJobId: string
+  tenantId: string
+  organizationId: string
+
+  // Event source
+  source: string
+  sourceEventId?: string | null
+
+  // Core event fields
+  eventType: string
+  eventCode: string
+  eventClassifierCode?: string | null
+  eventDateTime?: string | null
+  description?: string | null
+
+  // Equipment fields (critical for multi-container bookings)
+  equipmentReference?: string | null
+  isoEquipmentCode?: string | null
+  emptyIndicatorCode?: string | null
+  isTransshipmentMove?: boolean | null
+
+  // Location fields
+  locationName?: string | null
+  locationUnlocode?: string | null
+  locationCountry?: string | null
+  facilityCode?: string | null
+  facilityTypeCode?: string | null
+
+  // Transport call fields
+  vesselName?: string | null
+  vesselImo?: string | null
+  voyageNumber?: string | null
+  carrierServiceCode?: string | null
+  modeOfTransport?: string | null
+
+  // Document references
+  relatedDocumentReferences?: DocumentReference[] | null
+
+  // Metadata
+  publisherName?: string | null
+  publisherRole?: string | null
+}
+
+type ResolverContext = {
+  resolve: <T = unknown>(name: string) => T
+}
+
+export default async function handle(payload: TrackingEventCreatedPayload, ctx: ResolverContext) {
+  try {
+    const webhookService = ctx.resolve<any>('shipmentTrackingWebhookService')
+
+    await webhookService.dispatchEvent({
+      eventType: 'shipment_tracking.tracking_event.created',
+      payload: {
+        event: {
+          // IDs
+          id: payload.id,
+          trackingJobId: payload.trackingJobId,
+
+          // Event source
+          source: payload.source,
+          sourceEventId: payload.sourceEventId,
+
+          // Core event fields
+          eventType: payload.eventType,
+          eventCode: payload.eventCode,
+          eventClassifierCode: payload.eventClassifierCode,
+          eventDateTime: payload.eventDateTime,
+          description: payload.description,
+
+          // Equipment fields (critical for multi-container bookings)
+          equipmentReference: payload.equipmentReference,
+          isoEquipmentCode: payload.isoEquipmentCode,
+          emptyIndicatorCode: payload.emptyIndicatorCode,
+          isTransshipmentMove: payload.isTransshipmentMove,
+
+          // Location fields
+          locationName: payload.locationName,
+          locationUnlocode: payload.locationUnlocode,
+          locationCountry: payload.locationCountry,
+          facilityCode: payload.facilityCode,
+          facilityTypeCode: payload.facilityTypeCode,
+
+          // Transport call fields
+          vesselName: payload.vesselName,
+          vesselImo: payload.vesselImo,
+          voyageNumber: payload.voyageNumber,
+          carrierServiceCode: payload.carrierServiceCode,
+          modeOfTransport: payload.modeOfTransport,
+
+          // Document references
+          relatedDocumentReferences: payload.relatedDocumentReferences,
+
+          // Metadata
+          publisherName: payload.publisherName,
+          publisherRole: payload.publisherRole,
+        },
+      },
+      tenantId: payload.tenantId,
+      organizationId: payload.organizationId,
+    })
+  } catch (error) {
+    console.error('[shipment-tracking:subscriber] Failed to dispatch tracking_event.created webhook:', error)
+  }
+}