ConnectorRegistryService

Target

This page describes intended behaviour or structure. No implementation is claimed unless a section is explicitly marked Current implementation or Evidence.

Bounded context	BC-17 Connectors & Webhooks
Platform / plane	Integration Platform / Capability & Tools
Deployment granularity	module of host · host IntegrationHost
Status	target · ConnectSoft.Factory.Integration.Connectors
Built from	connectsoft-microservice · libraries: connectsoft-extensions-http-oauth2, connectsoft-extensions-saas-abstractions, connectsoft-extensions-messaging-model, connectsoft-extensions-messaging-model-orleans, connectsoft-extensions-persistence-model-nhibernate, connectsoft-extensions-rate-limiting, connectsoft-extensions-audit-net
Decisions	ADR-0012, ADR-0022
Traceability	FR-05 FR-11 FUX-02 NFR-05 NFR-13 NFR-18 XL-10 XL-15

Purpose and responsibilities

Provider, not code: a vendor is registered as a connector descriptor (capability interfaces, versioned adapter, retry and rate-limit profile, webhook scheme, configuration form) and becomes Active only after the conformance suite certified it. ConnectorRegistryService owns those descriptors, the subscriptions through which a tenant receives vendor events, and every delivery in both directions with deduplication, replay and a receipt. The June-2026 rows AzureDevOpsIntegrationService, GitHubIntegrationService, CloudProviderAdapterService and VendorApiClientRegistryService are adapters and descriptors here, not services; this service was added by the design plan because BC-17 had no module row.

Any capability exposed to agents is also a tool descriptor (BC-08) with a side-effect class; connectors never bypass the executor.

Context and boundaries

flowchart LR
    S["ConnectorRegistryService"]
    ToolAdapterService["ToolAdapterService"] -->|grpc| S
    WebhookGatewayService["WebhookGatewayService"] -->|event| S
    StudioBff["StudioBff"] -->|sync-http| S
    S -->|grpc| IntegrationService["IntegrationService"]
    S -->|grpc| SecretBrokerService["SecretBrokerService"]
    S -->|grpc| ArtifactService["ArtifactService"]
    S -->|event| WorkflowEngineService["WorkflowEngineService"]
    S -->|library| ext_client_libraries["ext-client-libraries"]
    S -. "ConnectorActivated" .-> E_ConnectorActivated(("event"))
    S -. "ConnectorDeprecated" .-> E_ConnectorDeprecated(("event"))
    S -. "ConnectorSubscriptionChanged" .-> E_ConnectorSubscriptionChanged(("event"))
    S -. "DeliveryReceived" .-> E_DeliveryReceived(("event"))
    S -. "DeliveryDispatched" .-> E_DeliveryDispatched(("event"))
    S -. "DeliveryFailed" .-> E_DeliveryFailed(("event"))
    S -. "DeliveryReplayed" .-> E_DeliveryReplayed(("event"))

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

Domain model

ConnectorDescriptor — A provider capability definition — capability interfaces (repositories, work items, pipelines, messaging, email, payments…), versioned client adapter, retry and rate-limit profile, webhook scheme (signature, replay window), configuration form and certification evidence. (catalog entry)

Field	Type	Required	Description
connectorId	string	yes
version	string	yes
tenantId	string	yes	Platform tenant for ConnectSoft connectors; tenants may register their own.
provider	string	yes
capabilities	list:string	yes	Capability interfaces implemented.
adapterRef	string	yes	Client library and version (first-party client, generic HTTP, OpenAPI, MCP).
retryProfile	json	yes
rateLimitProfile	json	yes
webhookScheme	json	no	Signature algorithm, header, replay window, deduplication key
configurationForm	string	yes	Descriptor of the settings a connection of this connector needs.
certificationRef	string	no	Conformance suite evidence (artifact).
state	enum:ConnectorState	yes
releaseId	string	no	Published asset release when distributed as an integration pack.

Invariants:

• A connector is Active only with certification evidence from the conformance suite; a changed adapter version re-runs certification.
• Every capability exposed to agents is also a tool descriptor (BC-08) with a side-effect class; the connector never bypasses the executor.
• Webhook schemes define signature verification and a replay window; a connector without a scheme accepts no inbound deliveries.

stateDiagram-v2
    Draft --> Certified : ConformanceSuitePassed
    Certified --> Active : Activate
    Active --> Deprecated : Deprecate

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

Events: ConnectorActivated, ConnectorDeprecated · Tables: ConnectorDescriptors · Repository: ConnectorDescriptorRepository

Subscription — A tenant's subscription to inbound events of a provider through a connection, with the event types, the target (workflow trigger, knowledge sync, fleet signal) and the verification state. (catalog entry)

Field	Type	Required	Description
subscriptionId	guid	yes
tenantId	string	yes
projectId	string	no
connectorId	string	yes
connectionId	guid	yes
eventTypes	list:string	yes
target	json	yes	kind: workflow-trigger
ingressRef	string	yes	GW-06 endpoint identity for this subscription.
active	bool	yes
lastDeliveryAt	datetime	no

Invariants:

• A subscription references an Active connector and an Active connection with a grant for subject kind Source or Tool.
• Inbound deliveries are accepted only for the subscription's event types and only after signature and replay verification.

Events: ConnectorSubscriptionChanged · Tables: Subscriptions · Repository: SubscriptionRepository

Delivery — One inbound or outbound delivery with verification, deduplication, dispatch, acknowledgement, failure and replay history; the receipt is the evidence. (catalog entry)

Field	Type	Required	Description
deliveryId	guid	yes
tenantId	string	yes
direction	enum:DeliveryDirection	yes
connectorId	string	yes
connectionId	guid	yes
subscriptionId	guid	no
externalId	string	yes	Vendor delivery id or idempotency key.
dedupKey	string	yes
state	enum:DeliveryState	yes
payloadRef	string	yes	Artifact reference (payload never in the row).
payloadHash	hash	yes
attempts	int	yes
receiptRef	string	no
receivedAt	datetime	yes
settledAt	datetime	no

Invariants:

• The same dedupKey within the replay window is Deduplicated, never dispatched twice.
• An outbound delivery of external class is sent only with the policy decision and approval the calling tool carried; the delivery records them.
• Replay after a vendor incident re-dispatches from the stored payload with a new attempt, never by asking the vendor to resend secrets.

stateDiagram-v2
    Received --> Verified : SignatureAndReplayChecked
    Received --> Rejected : VerificationFailed
    Verified --> Deduplicated : DuplicateWithinWindow
    Verified --> Dispatched : DispatchedToTarget
    Dispatched --> Acknowledged : TargetAcknowledged
    Dispatched --> Failed : TargetFailedAfterRetries
    Failed --> Replayed : OperatorReplay
    Replayed --> Dispatched : Redispatched

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

Events: DeliveryReceived, DeliveryDispatched, DeliveryFailed, DeliveryReplayed · Tables: Deliveries · Repository: DeliveryRepository

erDiagram
    ConnectorDescriptor {
        string connectorId PK
        string version
        string tenantId
        string provider
        list_string capabilities
        string adapterRef
        json retryProfile
        json rateLimitProfile
        json webhookScheme
        string configurationForm
        string certificationRef
        enum_ConnectorState state
        string releaseId
    }
    Subscription {
        guid subscriptionId PK
        string tenantId
        string projectId
        string connectorId
        guid connectionId
        list_string eventTypes
        json target
        string ingressRef
        bool active
        datetime lastDeliveryAt
    }
    Delivery {
        guid deliveryId PK
        string tenantId
        enum_DeliveryDirection direction
        string connectorId
        guid connectionId
        guid subscriptionId
        string externalId
        string dedupKey
        enum_DeliveryState state
        string payloadRef
        hash payloadHash
        int attempts
        string receiptRef
        datetime receivedAt
        datetime settledAt
    }

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

stateDiagram-v2
    [*] --> Received: inbound via GW-06 or outbound Deliver
    Received --> Verified: signature and replay checked
    Received --> Rejected: verification failed
    Verified --> Deduplicated: duplicate within the window
    Verified --> Dispatched: to target or vendor
    Dispatched --> Acknowledged
    Dispatched --> Failed: after retries
    Failed --> Replayed: operator replay
    Replayed --> Dispatched
    Acknowledged --> [*]
    Deduplicated --> [*]
    Rejected --> [*]

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

Entities and value objects

None modelled

No entities or value objects are modelled for this item yet.

Data model and storage

Store	Role	Engine / profile	Tables
Integration store	primary	azure-sql / nhibernate-sqlserver	ConnectorDescriptors, Subscriptions, Deliveries
Artifact content store	blob	blob / azure-blob	—

Table	Owner	Columns	Indexes
dbo.ConnectorDescriptors	ConnectorDescriptor	13	0
dbo.Subscriptions	Subscription	10	1
dbo.Deliveries	Delivery	15	2

Full DDL: appendix.

APIs

Method	Path	Operation	Scope	Side effects	Idempotency	Gateway	Summary
GET	/factory/connectors	ListConnectors	factory.connections.read	read	natural	GW-03	Connector descriptors with capabilities, adapter versions, webhook schemes and certification state.
POST	/factory/connectors/{connectorId}/certify	CertifyConnector	factory.connections.admin	sandbox	key-header	GW-03	Run the conformance suite against a connection of this connector (sandbox action; evidence as artifact).
POST	/factory/subscriptions	CreateSubscription	factory.connections.admin	external	key-header	GW-03	Subscribe to provider events through a connection; creates the GW-06 ingress identity.
GET	/factory/deliveries	ListDeliveries	factory.connections.read	read	natural	GW-03	Deliveries by direction, connector, state and time with receipts.
POST	/factory/deliveries/{deliveryId}/replay	ReplayDelivery	factory.connections.operate	shared-write	natural	GW-03	Re-dispatch a failed inbound delivery from the stored payload (Operator).

gRPC service	Method	Streaming	Visibility	Side effects	Summary
Connectors	Deliver	none	internal	external	Outbound delivery through a connector with the calling tool's policy decision and approval; returns the receipt.
Connectors	ResolveCapability	none	internal	read	Resolve a capability interface to the adapter and connection for a scope.

Messages

Event	Topic	Scope / v	Aggregate	Consumers	Summary
ConnectorActivated	connectors.connectors.v1.connector-activated	integration / 1	ConnectorDescriptor	ToolAdapterService, StudioBff, AuditService	A certified connector version is usable.
ConnectorDeprecated	connectors.connectors.v1.connector-deprecated	integration / 1	ConnectorDescriptor	ToolAdapterService, StudioBff	A connector version is deprecated.
ConnectorSubscriptionChanged	connectors.subscriptions.v1.connector-subscription-changed	integration / 1	Subscription	WebhookGatewayService, StudioBff, AuditService	A subscription was created, changed or deactivated.
DeliveryReceived	connectors.deliveries.v1.delivery-received	integration / 1	Delivery	PipelineExecutionService, WorkflowEngineService, KnowledgeIngestionService, DashboardService	A verified inbound delivery was recorded.
DeliveryDispatched	connectors.deliveries.v1.delivery-dispatched	integration / 1	Delivery	DashboardService, AuditService	An inbound delivery reached its target or an outbound delivery was sent.
DeliveryFailed	connectors.deliveries.v1.delivery-failed	integration / 1	Delivery	AlertRuleService, StudioBff, StudioNotificationService, DashboardService, AuditService	Delivery failed after retries.
DeliveryReplayed	connectors.deliveries.v1.delivery-replayed	integration / 1	Delivery	AuditService	An operator replayed a failed delivery.

ConnectorActivated payload:

Field	Type	Required	Description
connectorId	string	yes
version	string	yes
tenantId	string	yes
provider	string	yes

ConnectorDeprecated payload:

Field	Type	Required	Description
connectorId	string	yes
version	string	yes
tenantId	string	yes

ConnectorSubscriptionChanged payload:

Field	Type	Required	Description
subscriptionId	guid	yes
tenantId	string	yes
connectorId	string	yes
active	bool	yes

DeliveryReceived payload:

Field	Type	Required	Description
deliveryId	guid	yes
tenantId	string	yes
connectorId	string	yes
subscriptionId	guid	no
eventType	string	yes
payloadHash	hash	yes

DeliveryDispatched payload:

Field	Type	Required	Description
deliveryId	guid	yes
tenantId	string	yes
direction	enum:DeliveryDirection	yes
receiptRef	string	yes

DeliveryFailed payload:

Field	Type	Required	Description
deliveryId	guid	yes
tenantId	string	yes
direction	enum:DeliveryDirection	yes
reason	string	yes

DeliveryReplayed payload:

Field	Type	Required	Description
deliveryId	guid	yes
tenantId	string	yes
replayedBy	string	yes

Command	Handled by	Result events	Summary
CertifyConnector	ConnectorDescriptor	ConnectorActivated
CreateSubscription	Subscription	ConnectorSubscriptionChanged
Deliver	Delivery	DeliveryDispatched, DeliveryFailed
ReplayDelivery	Delivery	DeliveryReplayed

Event	Producer	Handler	Purpose
InboundDeliveryVerified	WebhookGatewayService	RecordAndDispatch	Record a verified inbound delivery, deduplicate and dispatch to its target.
ConnectionStateChanged	IntegrationService	PauseOnRevocation	Deactivate subscriptions and fail pending deliveries of a revoked connection.

Workers and jobs

Worker	Trigger	Output events	Retry	Idempotency key	Summary
OutboundDeliveryRetrier	schedule */1 * * * *	DeliveryDispatched, DeliveryFailed	exponential	deliveryId + attempts	Retries failed outbound deliveries per the connector's retry profile within the calling tool's budget; final failure emits DeliveryFailed.
InboundDispatcher	event	DeliveryReceived, DeliveryDispatched, DeliveryFailed	exponential	dedupKey	Dispatches verified inbound deliveries to workflow triggers, knowledge sync or fleet signals and acknowledges.
ConformanceRunner	manual on CertifyConnector	ConnectorActivated	fixed	connectorId + version + suiteVersion	Runs the connector conformance suite (capability calls against a sandbox connection) and records certification evidence.

Actors and grains

None modelled

No grains are modelled for this item yet.

Sagas and long-running flows

None modelled

No sagas are modelled for this item yet.

sequenceDiagram
    participant V as Vendor
    participant W as WebhookGatewayService
    participant C as ConnectorRegistryService
    participant E as WorkflowEngineService
    V->>W: POST /webhooks/{ingressRef}
    W->>W: known ingress, signature, replay window, capture payload
    W-)C: InboundDeliveryVerified
    C->>C: deduplicate on key, Delivery Verified
    C-)E: DeliveryReceived (workflow trigger)
    C->>C: Dispatched, Acknowledged, receipt

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

Options and configuration

Section	Key	Type	Default	Reloadable	Secret	Summary
Integration:Connectors	ReplayWindowMinutes	int	60	yes	no	Deduplication window for inbound deliveries.
Integration:Connectors	DefaultRetry	json	{ attempts: 5, backoff: exponential, base: 30s }	yes	no	Retry profile when the connector sets none.

Metrics and observability

Metric	Instrument	Unit	Dimensions	Summary
connectsoft.factory.integration.deliveries	counter	{delivery}	tenant, connector, direction, state	Deliveries by outcome.
connectsoft.factory.integration.delivery_latency	histogram	s	connector, direction	Receive-to-dispatch and send latencies.
connectsoft.factory.integration.connectors	updown	{connector}	provider, state	Connectors by state.
connectsoft.factory.integration.subscriptions	updown	{subscription}	tenant, connector	Active subscriptions.

Security

Authentication	client-credentials
Scopes	factory.connections.read (Read connectors, subscriptions, deliveries.); factory.connections.admin (Certify connectors, manage subscriptions.); factory.connections.operate (Replay deliveries (Operator).)
Roles	Operator, WorkspaceAdmin, PlatformAdmin, Observer
Tenant isolation	row-filter
Data classification	confidential
Max side-effect class	external
Secrets	—

Dependencies

Outbound

Target	Kind	Purpose	Failure mode	Required
IntegrationService	grpc	Resolve connections and grants.	fail-fast	yes
SecretBrokerService	grpc	Short-lived credentials for deliveries.	fail-fast	yes
ArtifactService	grpc	Payloads, receipts and certification evidence by hash.	fail-fast	yes
WorkflowEngineService	event	Workflow triggers from inbound events.	queue	no
ext-client-libraries	library	First-party vendor clients as adapters.	degrade	no

Inbound

Target	Kind	Purpose	Failure mode	Required
ToolAdapterService	grpc	Deliver for external-class tools.	—	yes
WebhookGatewayService	event	Verified inbound deliveries.	—	yes
StudioBff	sync-http	Connector, subscription and delivery views.	—	yes

Failure and recovery

Scenario	Detection	Recovery	Data impact	RTO (min)
Vendor rejects outbound delivery	adapter error	retry per profile within budget; DeliveryFailed with receipt; the calling tool reports Failed or Uncertain	none	0
Inbound burst after a vendor incident	delivery rate spike	rate limiting at GW-06; deduplication by key; dispatch queue drains	delayed dispatch	60

NFR targets

Target	Class value (pilot-interactive)	Override
latency_p95_ms	2000	—
availability_pct	99.5	—
throughput_rps	50	—
rpo_minutes	15	—
rto_minutes	240	—
cost_class	low	—

Deployment

Granularity	module of host · host IntegrationHost
Topologies	saas-default, hybrid, on-prem
Runtime	—; replicas —–—
Ports	—

Current implementation

The first-party clients exist as libraries; no descriptor, certification, subscription or delivery lifecycle exists. The June-2026 workflows page (archived) described vendor onboarding and webhook flows that this service realises.

Later capabilities

Integration packs (descriptor, clients, capabilities, profiles, schemes, forms) as marketplace assets seeded from the first-party clients; agent-drafted packs from OpenAPI or SDK specs for human review; every registered capability exposed as a governed MCP tool automatically; webhook replay after vendor incidents at scale; vendor cost attribution.

Decisions and traceability

Family	Ids
FR	FR-05, FR-11
FUX	FUX-02
NFR	NFR-05, NFR-13, NFR-18
XL	XL-10, XL-15

Related

• Integration workflows · IntegrationService · WebhookGatewayService · ToolAdapterService

• Integration Platform microservices · bounded contexts · APIs · events · data model

• Services catalog · Ownership map