Events¶

Target Architecture — Final-State Design

This page defines the final-state messaging contract of the Integration Platform. All messages travel in the canonical event envelope over MassTransit on Azure Service Bus. Commands use VerbNoun; events use NounVerbPastTense, per the naming conventions.

The Integration Platform is event-driven end to end. Inbound webhooks are normalised into events; outbound deliveries are driven by events; every connection, run, delivery, and rotation emits a fact that the rest of the factory — especially the Knowledge Platform and Observability & Feedback Platform — can correlate by traceId.

Commands¶

Commands express intent and are handled by exactly one aggregate. They are not part of the public event stream.

Command	Handled By	Purpose
`EstablishIntegrationConnection`	`IntegrationConnection`	Create and test a new connection to a provider
`RegisterIntegrationProvider`	`IntegrationProvider`	Register a provider and its capabilities in the Vendor Registry
`RegisterExternalApiClient`	`ExternalApiClient`	Register a versioned reusable API client for a provider
`SubscribeWebhook`	`WebhookSubscription`	Create an outbound webhook subscription
`DeliverWebhook`	`WebhookDelivery`	Deliver a payload to a subscribed endpoint
`IngestWebhook`	`WebhookDelivery`	Accept and normalise an inbound webhook
`ExecuteIntegrationRun`	`IntegrationRun`	Execute a governed outbound operation
`RotateCredential`	`IntegrationCredential`	Rotate a stored credential version
`RetryIntegrationRun`	`IntegrationRun`	Retry a failed run per policy

Domain Events¶

Facts emitted by an aggregate after a state change, published within the platform.

Domain Event	Emitted By	Meaning
`IntegrationConnectionEstablished`	`IntegrationConnection`	A connection was created and passed its first health test
`IntegrationConnectionRetired`	`IntegrationConnection`	A connection was disabled/retired
`IntegrationProviderRegistered`	`IntegrationProvider`	A provider was registered in the Vendor Registry
`ExternalApiClientRegistered`	`ExternalApiClient`	A versioned API client was registered for a provider
`WebhookSubscribed`	`WebhookSubscription`	An outbound webhook subscription was created
`WebhookDelivered`	`WebhookDelivery`	A webhook (inbound normalised or outbound) was successfully processed/delivered
`IntegrationRunCompleted`	`IntegrationRun`	An outbound operation completed successfully
`IntegrationFailed`	`IntegrationRun` / `IntegrationFailure`	An operation, delivery, or health probe failed
`CredentialRotated`	`IntegrationCredential`	A credential was rotated and re-verified

Integration Events¶

Domain events promoted to cross-platform contracts. These are the versioned, externally consumed events listed in the factory-wide Event Catalog.

Integration Event	Primary Consumers	Purpose
`IntegrationConnectionEstablished`	Control Plane, Knowledge Platform	Record availability of a new external connection
`WebhookSubscribed`	Control Plane, Governance	Track outbound data egress subscriptions
`WebhookDelivered`	Knowledge Platform, Observability	Inbound external event entering the factory / confirmed egress
`IntegrationRunCompleted`	DevOps & GitOps, Control Plane, Observability	Result of an external operation (e.g. PR opened, message sent)
`IntegrationFailed`	Observability & Feedback, Control Plane	External failure for alerting, retry, and escalation
`CredentialRotated`	Governance, Security & Compliance	Audit trail for credential lifecycle

Envelope¶

Every message uses the canonical envelope. An illustrative IntegrationRunCompleted:

{
  "eventId": "evt-3a6e1d40-2e44-4c1a-9b6d-0f2a8c3d5e10",
  "eventType": "IntegrationRunCompleted",
  "tenantId": "connectsoft",
  "projectId": "proj-booking-saas",
  "moduleId": "module-github-integration",
  "traceId": "trace-9f1c2b7d",
  "correlationId": "corr-3a6e1d40",
  "causationId": "evt-run-requested",
  "occurredAt": "2026-06-11T09:03:02Z",
  "payload": {
    "runId": "run-3a6e1d40",
    "connectionId": "conn-7b3c1f9a",
    "providerId": "prov-github",
    "operation": "OpenPullRequest",
    "attempts": 1,
    "outcome": "Success",
    "externalRef": "PR#482"
  }
}

Selected fields are mirrored into Service Bus application properties (cs-event-type, cs-tenant-id, cs-trace-id, cs-correlation-id, cs-schema-version) so subscriptions filter without deserializing the body.

Topics¶

Events are published to Azure Service Bus topics with per-context subscriptions. Topic naming mirrors the platform and context.

Topic	Carries	Representative Subscribers
`factory.integration.connections`	`IntegrationConnectionEstablished`, `IntegrationConnectionRetired`	Control Plane, Knowledge Platform
`factory.integration.providers`	`IntegrationProviderRegistered`, `ExternalApiClientRegistered`	Vendor Registry consumers, Knowledge Platform
`factory.integration.webhooks`	`WebhookSubscribed`, `WebhookDelivered`	Knowledge Platform, Observability, Governance
`factory.integration.runs`	`IntegrationRunCompleted`, `IntegrationFailed`	DevOps & GitOps, Observability, `IntegrationRetryWorker`
`factory.integration.credentials`	`CredentialRotated`, `IntegrationFailed` (rotation)	Governance, Security & Compliance

Event Flow¶

flowchart TB
    subgraph Inbound["Inbound (vendor → factory)"]
        Ext["Vendor webhook"] --> GW["WebhookGatewayService"]
        GW -->|"normalize"| Delivered["WebhookDelivered"]
        Delivered --> BusIn[("factory.integration.webhooks")]
        BusIn --> KP["Knowledge Platform"]
    end

    subgraph Outbound["Outbound (factory → vendor)"]
        Cmd["ExecuteIntegrationRun"] --> Run["IntegrationRun"]
        Run -->|success| Completed["IntegrationRunCompleted"]
        Run -->|failure| Failed["IntegrationFailed"]
        Completed --> BusRuns[("factory.integration.runs")]
        Failed --> BusRuns
        BusRuns --> Retry["IntegrationRetryWorker"]
        BusRuns --> OBS["Observability & Feedback"]
    end

    subgraph Lifecycle["Connection & credential lifecycle"]
        Est["IntegrationConnectionEstablished"] --> BusConn[("factory.integration.connections")]
        Rotated["CredentialRotated"] --> BusCred[("factory.integration.credentials")]
        BusCred --> GOV["Governance, Security & Compliance"]
    end

Hold "Alt" / "Option" to enable pan & zoom