--- id: CON-PFM-INT-004 name: Integration Event feature: FEAT-PFM-INT-04 product_area: platform module: integrations revision: 1 status: draft product_intent: proposed implementation_evidence: observed source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 macroservice-libraries: 54536a441935c6e09fdb7f96f0bec71c52ba4e03 definition: >- An integration event is information exchanged across the provider boundary: a retained notification, an application-routed event or a subscribed Rhythm change. owned_by: MOD-PFM-INT synonyms: - Webhook - Notification - Delivery not_to_be_confused_with: - Application-owned event for automation - Outgoing request to a provider facets: - name: Webhook endpoint meaning: An endpoint provides a connection-specific public notification address and verification secret. used_for: Accepting messages from the provider. - name: Received message meaning: 'Retained notification material has verification, processing, duplicate and failure outcomes.' used_for: Supporting controlled processing and recovery replay. - name: Integration event meaning: A typed internal event carries interpreted provider information to matching applications. used_for: Updating consumers such as Accounting or returning completion results. - name: Consumer meaning: Each application registers the event types or prefixes its intake handles. used_for: Matching an event to its application recipients. - name: Subscription meaning: >- An accepted event interest associates an installation with a delivery destination and optional condition. used_for: Selecting Rhythm changes to send outside the application. - name: Delivery meaning: 'A subscription’s projected change retains pending, delivered, skipped or dead standing.' used_for: Following outbound work and handling delivery failure. relationships: - to: CON-PFM-INT-002 statement: Connection disconnection disables its notification endpoints. provenance: test source: >- services-platform:modules/integrations/tests/integration/services/connections/transition.integration.spec.js#disables the connection’s webhook endpoints - to: CON-PFM-INT-001 statement: Installation removal deletes its event subscriptions. provenance: test source: >- services-platform:modules/integrations/tests/integration/services/connections/disconnect-discard-uninstall.integration.spec.js#removes every subscription of the installation with the uninstallation, and no other installation’s - to: CON-PFM-INT-003 statement: Asynchronous completion is routed back to the initiating application. provenance: test source: >- services-platform:modules/integrations/tests/e2e-adapters/events-dummy.adapters.spec.js#reaches the consumer of the application that invoked it, carrying the response lifecycle: - state: received meaning: Notification material is retained pending verification. how_it_changes: A worker validates and interprets it. - state: processed or ignored meaning: A verified notification produced events or matched an earlier message. how_it_changes: Explicit replay requests another processing pass. - state: rejected or dead meaning: Verification or repeated processing failure ended automatic work. how_it_changes: Operators may request recovery replay. acted_on_by: - CAP-PFM-INT-013 - CAP-PFM-INT-014 - CAP-PFM-INT-015 visible_to: - ACT-PFM-017 - ACT-PFM-018 - ACT-PFM-019 - ACT-PFM-020 - ACT-PFM-021 - ACT-PFM-006 evidence: - >- services-platform source inventory: modules/integrations/services/webhooks/*, services/events/*, services/subscriptions/*, db/integration-webhook-*.table.ts, integration-events.table.ts, integration-subscriptions.table.ts, integration-deliveries.table.ts; docs/integrations/README.md (Webhooks, Integration events, Subscriptions and deliveries); docs/milestones/INTG-M3-webhooks-events-deliveries.md. - 'macroservice-libraries source inventory: packages/integration-contracts/src/events.ts, domain-events.ts.' supersedes: [] --- # Integration Event ## What It Is An integration event represents information moving across the boundary between Rhythm and a provider. A provider can send a notification about an account operation. Rhythm retains that incoming message, verifies it through the adapter and turns its meaning into a typed event for consuming applications. In the opposite direction, an application change can become a projected delivery for a subscribed integration. These forms share a need for identity, routing and visible processing results, but they have different origins. The received provider message preserves what arrived. The internal event expresses a meaning an application can consume. The outgoing delivery is one subscription’s copy of a Rhythm change. Keeping those distinctions helps Product investigate where a missing update stopped rather than describe every item simply as a webhook. ## What It Is Not A notification is information about something that happened, rather than an instruction to repeat a provider operation. A capability call has its own request and settlement. An application business event may trigger workflow automation, but its publication and host processing remain separate from the provider notification record. A subscription likewise represents a saved interest rather than one individual delivery. ## How It Is Used Administrators configure endpoints and subscriptions, inspect messages and deliveries, and request replay when a processing problem is corrected. Readers inspect those records without receiving signing secrets or initiating recovery. Application consumers interpret routed events for their own business records and report whether they handled, ignored or need another attempt. Useful investigation follows the message from receipt through interpretation and routing. A retained message gives replay something concrete to process. A dead delivery tells staff automatic work ended, while an unclaimed internal event identifies a missing consumer. Retry can deliver an event again, so consumers need to recognize its identity rather than treat every arrival as a new business fact. ## Its Facets **Endpoint.** A public address belongs to a connection and notification kind. Its secret supports verification, with a separate setup and rotation lifecycle. **Received message.** Stored body and selected headers preserve the incoming material. Verification, duplicate handling and processing determine whether it produces events. **Typed event and consumer.** Event contracts describe interpreted information. Consumers register interests, and completion routing additionally respects the application that made the call. **Subscription.** The installation’s accepted event interests and optional conditions govern which Rhythm changes are eligible to leave the application. **Delivery.** Each projected change retains its own progress. Push acknowledgement, pull cursor movement, repeated failure and operator replay give different ways to explain that progress. ## How It Relates Connection removal disables notification endpoints. Installation removal deletes its subscriptions. Capability settlement produces completion events, and matching provider references can relate a notification to the Rhythm record responsible for the provider object. Extension business-event declarations are neighbouring shared information, but external delivery belongs to the integration path rather than a second customer subscription system. ## What It Could Become The product should decide the acceptance boundary for this machinery through the proposed webhook and event milestone. Retry semantics need a clear consumer contract, including the possibility of another delivery to a consumer that already handled an earlier attempt. Product also needs to distinguish pull delivery from the unbuilt synchronization-profile experience. Working service code and retained messages establish implementation evidence, while recovery promises and additional delivery channels still require product decisions.