Integration Service

integration-service is a Quarkus service that owns three integration concerns for ShopSTAR3: outbound webhook delivery, API credential issuance for external consumers, and a pluggable connector framework for marketplace and iPaaS-style integrations. ERP adapters and cXML live in enterprise-service. Webhook signing secrets and connector API credentials are stored in Vault.

Webhook Delivery#

Store admins register webhook endpoint subscriptions and select which domain event types to receive. integration-service consumes all domain events from the platform Kafka bus and fans deliveries out to matching subscriptions.

Delivery#

Each matched subscription receives an HTTP POST to its target_url with:

• Body: JSON event payload
• X-SS3-Event: event type (e.g. order.placed)
• X-SS3-Delivery: delivery ID (idempotency for the receiver)
• X-SS3-Signature: HMAC-SHA256(signingSecret, rawBody) — for receiver verification

Retry Policy#

Delivery is at-least-once. Failed deliveries are retried with exponential backoff:

Dead-lettered deliveries are visible in the admin panel and can be manually re-triggered.

Data Model#

webhook_subscriptions — subscription_id UUID PK, store_id, name, target_url, events TEXT[] (subscribed event types), is_active. Signing secret in Vault per subscription.

webhook_deliveries — delivery_id UUID PK, subscription_id FK, store_id, event_type, event_id UUID (source event idempotency key), event_payload JSONB, http_status, response_body, attempt_number, next_retry_at, delivered_at, status ENUM (PENDING / DELIVERED / FAILED / DEAD_LETTERED).

api_credentials — credential_id UUID PK, store_id, name, type ENUM (API_KEY / OAUTH_CLIENT), client_id (publicly visible prefix or OAuth client ID), hashed_secret (bcrypt — never returned after creation), scopes TEXT[], is_active, last_used_at, expires_at, created_by.

connector_configs — config_id UUID PK, store_id, connector_type, display_name, is_active, event_subscriptions TEXT[], settings JSONB (non-sensitive). Connector API credentials in Vault per config.

connector_sync_log — per-run record of direction (INBOUND / OUTBOUND), entity type, record count, status, and error summary.

API Credential Management#

External consumers authenticate to SS3 APIs using API keys or OAuth 2.0 client credentials. Both are issued and managed by integration-service.

Scope Model#

Scopes follow the pattern {resource}:{action}:

Gateway Validation#

The gateway calls GET /credentials/validate on every inbound request bearing an API key or client credentials. integration-service looks up the credential, verifies the bcrypt hash, checks active/expiry status, updates last_used_at, and returns { storeId, scopes, valid }. The gateway caches valid responses for 60 seconds to reduce hot-path latency.

Plain-text secrets are returned exactly once at creation time. After that only the bcrypt hash is stored.

Connector Framework#

The connector framework allows marketplace and third-party platform integrations to be configured per store without changing core service code.

interface ConnectorAdapter {
    String connectorType();
    void handleEvent(DomainEvent event);
    void poll();
}

Initial connectors:

gRPC Interface#

integration-service does not expose gRPC methods. It provides a REST endpoint for gateway credential validation and communicates with the rest of the platform through Kafka.

Kafka Topics#

Consumed#

All platform event topics. For each event, integration-service:

1. Fans out to matching webhook subscriptions
2. Fans out to matching connector configs

Published#

webhook.dead_lettered is consumed by communication-service to notify the store admin.

Vault Configuration#