---
id: WF-PFM-INT-017
title: Route integration events to application consumers
trigger: The initiating application deploy starts this flow.
product_area: platform
module: integrations
revision: 1
status: draft
design_intent: proposed
implementation_evidence: observed
inference: []
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
implements:
  - CAP-PFM-INT-015
moves:
  - STATE-PFM-INT-010
crosses: []
idempotency: Event identifiers remain stable across routing attempts and consumer recipients must deduplicate them.
concurrency: >-
  A numbered event-attempt claim rejects duplicates of that attempt, while later attempts can repeat consumer
  calls.
hops:
  - 'n': 1
    actor_or_service: Application deploy
    action: Register the application’s consumer function and event interests using its own principal.
    anchor: 'services-platform:modules/integrations/aws/api/registration.routes.ts'
    seam: sync
    on_failure: Return registration refusal to the deployment.
    left_inconsistent: The preceding consumer declaration remains.
    observer: Deploy logs
    provenance: observed
    source: 'services-platform:modules/integrations/aws/api/registration.routes.ts'
  - 'n': 2
    actor_or_service: Adapter
    action: Accept at most one hundred valid produced events for an account the adapter serves.
    anchor: 'services-platform:modules/integrations/services/adapter-callbacks/adapter-callbacks.ts:emitAdapterEvents'
    seam: sync
    on_failure: Reject the complete invalid event batch.
    left_inconsistent: No partial batch is retained.
    observer: Adapter logs
    provenance: observed
    source: 'services-platform:modules/integrations/services/adapter-callbacks/adapter-callbacks.ts:emitAdapterEvents'
  - 'n': 3
    actor_or_service: Message work dispatcher
    action: Publish retained event-routing dispatch work to the events queue.
    anchor: 'services-platform:modules/integrations/services/work/work-dispatcher.ts:dispatchWork'
    seam: queue
    on_failure: Keep failed publication work for another pass.
    left_inconsistent: Repeated queue delivery is possible and must be claimed by attempt number.
    observer: Dispatcher silence alarm
    provenance: observed
    source: 'services-platform:modules/integrations/services/work/work-dispatcher.ts:dispatchWork'
  - 'n': 4
    actor_or_service: Integration event router
    action: >-
      Invoke matching consumers in batches of ten or fewer, restricting completion events to the caller’s
      application.
    anchor: 'services-platform:modules/integrations/services/events/event-router.ts:routeIntegrationEvents'
    seam: sync
    on_failure: 'Retry invocation failure or an explicit retry outcome, then mark dead after the limit.'
    left_inconsistent: Consumers already successful can be invoked again on a later attempt.
    observer: Events screen and Rhythm HQ list
    provenance: observed
    source: 'services-platform:modules/integrations/services/events/event-router.ts:routeIntegrationEvents'
  - 'n': 5
    actor_or_service: Consuming application
    action: >-
      Expect the external application to apply events and recognize duplicate identifiers; host implementation
      is outside this source boundary.
    anchor: 'services-platform:modules/integrations/services/events/event-router.ts:routeIntegrationEvents'
    seam: sync
    on_failure: The consumer contract can request retry.
    left_inconsistent: Application records may lag while the event remains unresolved.
    observer: The application
    provenance: unknown
    source: FND-PFM-INT-030
  - 'n': 6
    actor_or_service: Integration event router
    action: 'Save each event’s delivered, retrying, dead or unclaimed result and any next dispatch work.'
    anchor: 'services-platform:modules/integrations/services/events/event-router.ts:routeIntegrationEvents'
    seam: sync
    on_failure: A settlement failure does not undo earlier consumer calls or earlier committed event results.
    left_inconsistent: Unrecorded outcomes need recovery even if some applications already acted.
    observer: Rhythm HQ event list
    provenance: observed
    source: 'services-platform:modules/integrations/services/events/event-router.ts:routeIntegrationEvents'
evidence:
  - >-
    services-platform at ad3f6a65: modules/integrations/services/events/event-router.ts, complete-event.ts;
    services/adapter-callbacks/adapter-callbacks.ts; aws/api/registration.routes.ts
    (registerIntegrationEventConsumer); docs/integrations/README.md (Integration events)
  - >-
    services-platform:modules/integrations/tests/integration/services/events/event-router.integration.spec.js#replaces
    what a principal registered before, whole
  - >-
    services-platform:modules/integrations/tests/integration/services/adapter-callbacks/adapter-callbacks.integration.spec.js#refuses
    a type the manifest does not produce, InvalidRequest
  - >-
    services-platform:modules/integrations/tests/integration/services/events/event-router.integration.spec.js#lists
    the events nobody took for Rhythm HQ, across tenants
controls: [TC-AVL-001, TC-AVL-004, TC-AVL-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-CHG-001, TC-CHG-002, TC-CHG-003, TC-CHG-004, TC-CHG-005, TC-CHG-006, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-IAM-001, TC-IAM-002, TC-IAM-003, TC-IAM-004, TC-IAM-005, TC-IAM-006, TC-LOG-001, TC-LOG-004, TC-LOG-005, TC-MON-001, TC-MON-002, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-PRV-001, TC-PRV-002, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-TEN-004, TC-VEN-001, TC-VEN-002, TC-VEN-003]
---

# Route integration events to application consumers

## What It Does

Applications declare consumers for provider event types at deploy. Routing claims a numbered attempt, invokes each matching consumer and records outcomes separately. Completion events restrict that selection to the application that requested the provider call.

## The Flow

```mermaid
sequenceDiagram
  participant P0 as Application deploy
  participant P1 as Adapter
  participant P2 as Message work dispatcher
  participant P3 as Integration event router
  participant P4 as Consuming application
  P0->>P0: 1. Register the application’s consumer function and event interests using its own principal.
  P1->>P1: 2. Accept at most one hundred valid produced events for an account the adapter serves.
  P2->>P2: 3. Publish retained event-routing dispatch work to the events queue.
  P3->>P3: 4. Invoke matching consumers in batches of ten or fewer
  P4->>P4: 5. Expect the external application to apply events and recognize duplicate identifiers
  P3->>P3: 6. Save each event’s delivered
```

## When Something Fails

Return registration refusal to the deployment. The preceding consumer declaration remains. Reject the complete invalid event batch. No partial batch is retained. Keep failed publication work for another pass. Repeated queue delivery is possible and must be claimed by attempt number. Retry invocation failure or an explicit retry outcome, then mark dead after the limit. Consumers already successful can be invoked again on a later attempt. The consumer contract can request retry. Application records may lag while the event remains unresolved. A settlement failure does not undo earlier consumer calls or earlier committed event results. Unrecorded outcomes need recovery even if some applications already acted.

## Open Design Questions

The approved planning layer already describes repeat delivery and consumer deduplication; this design cites that obligation rather than claiming a new decision. Host effects are outside the examined code boundary.