> For the complete documentation index, see [llms.txt](https://host2host.onibonje.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://host2host.onibonje.com/docs/47-gateway-entrypoints.md).

# H2H Gateway Entry Points

## 1. Overview

Partners reach the platform through **five database-driven entry point types**. All ingress converges on the same Apache Camel pipeline and canonical message model — no separate business logic per channel.

| Entry point       | `channel_type` | Pattern                  | Typical use                                     |
| ----------------- | -------------- | ------------------------ | ----------------------------------------------- |
| **SFTP / file**   | `SFTP`         | Async batch              | Bulk payments, statements, large files          |
| **HTTP**          | `HTTP`         | Sync request/response    | REST/JSON payments, status inquiry, SOAP legacy |
| **WebSocket**     | `WEBSOCKET`    | Persistent bidirectional | Real-time status, ACK push, live dashboards     |
| **Message queue** | `MQ`           | Async message            | IBM MQ, JMS, high-throughput corporate bus      |
| **Signed URL**    | `SIGNED_URL`   | HTTPS file without SFTP  | Direct bucket upload/download                   |

**Rule:** Entry point behaviour (paths, auth, limits, subscriptions) is configured in **`channel_config`** — not hardcoded in routes or gateway config files.

See also: [39 API Gateway Architecture](/docs/39-api-gateway-architecture.md), [15 File Management System](/docs/15-file-management-system.md), [28 MQ/JMS Adapter](/docs/28-mq-jms-adapter.md), [04 Database-Driven Configuration](/docs/04-database-driven-configuration.md).

***

## 2. Architecture

```mermaid
flowchart TB
  subgraph partners [Partner Systems]
    ERP[ERP / Corporate]
    Fin[Fintech]
  end

  subgraph entry [H2H Gateway Entry Points - DB-configured]
    SFTP[SFTP / PGP]
    HTTP[HTTP REST SOAP]
    WS[WebSocket]
    MQ[MQ / JMS]
    URL[Signed URL]
  end

  subgraph perimeter [Perimeter]
    Kong[Kong / Apigee]
    WSS[WebSocket Gateway]
  end

  subgraph runtime [h2h-runtime - Camel]
    Resolver[ChannelConfigResolver]
    Routes[Integration Routes]
    Canon[Canonical Model]
  end

  ERP --> SFTP
  ERP --> HTTP
  Fin --> HTTP
  Fin --> WS
  ERP --> MQ

  HTTP --> Kong
  WS --> WSS
  Kong --> Routes
  WSS --> Routes
  SFTP --> Routes
  MQ --> Routes
  URL --> Routes

  Resolver --> Routes
  Routes --> Canon
```

***

## 3. Database-Driven Channel Configuration

**Table:** `channel_config` (extended)

| Column                   | Description                                                        |
| ------------------------ | ------------------------------------------------------------------ |
| `channel_id`             | UUID                                                               |
| `partner_id`             | FK                                                                 |
| `channel_type`           | `SFTP`, `HTTP`, `WEBSOCKET`, `MQ`, `SIGNED_URL`                    |
| `protocol`               | For HTTP: `REST`, `SOAP`; for MQ: `IBM_MQ`, `KAFKA_INGRESS`, `JMS` |
| `connection_params`      | JSON — type-specific (see §4–§6)                                   |
| `integration_profile_id` | Default profile for this channel                                   |
| `enabled`                | Boolean                                                            |
| `environment`            | `sandbox`, `production`                                            |

On publish, gateway plugins and Camel ingress endpoints **reload from DB** (same pattern as SFTP `DynamicSftpEndpoint`).

***

## 4. HTTP Entry Point

### 4.1 Role

**Synchronous** partner integration — request in, accept/reject (or inquiry result) in the same HTTP connection. Covers REST/JSON and SOAP/XML.

| Concern                        | Owner                              |
| ------------------------------ | ---------------------------------- |
| TLS, WAF, rate limit, API keys | API gateway (Kong/Apigee)          |
| Path → Camel route mapping     | `channel_config` + admin           |
| Business logic                 | Camel routes (shared with file/MQ) |

### 4.2 `connection_params` (HTTP)

```json
{
  "basePath": "/v1/partners/acme",
  "methods": ["POST", "GET"],
  "contentTypes": ["application/json", "application/xml"],
  "gatewayRouteId": "partner-acme-payments",
  "syncTimeoutMs": 30000,
  "idempotencyHeader": "X-Idempotency-Key",
  "correlationHeader": "X-Correlation-Id",
  "authMode": "MTLS",
  "authRef": "vault:secret/partners/acme/api",
  "rateLimitTier": "PREMIUM",
  "soapWsdlRef": null,
  "maxBodyBytes": 5242880
}
```

### 4.3 Flow

```mermaid
sequenceDiagram
  participant P as Partner
  participant GW as API Gateway
  participant C as Camel HTTP route
  participant CBS as Core Banking

  P->>GW: POST /v1/payments (JSON + idempotency key)
  GW->>GW: mTLS, rate limit, correlation ID
  GW->>C: platform-http (channel resolved from DB)
  C->>C: validate, transform, idempotency
  C->>CBS: postPayment
  CBS-->>C: result
  C-->>GW: 200 / 422 + correlationId
  GW-->>P: sync response
```

### 4.4 Camel integration

| Component | URI pattern                                                                    |
| --------- | ------------------------------------------------------------------------------ |
| REST      | `platform-http:{{channel.basePath}}` — paths from `channel_config`             |
| SOAP      | `cxf:bean:partnerSoapEndpoint` — WSDL URL from `connection_params.soapWsdlRef` |

**Module:** `h2h-http-ingress` (optional JAR) or `h2h-camel-core` `DynamicHttpEndpoint`.

***

## 5. WebSocket Entry Point

### 5.1 Role

**Real-time, server-push** integration for partners that need live updates without polling HTTP:

* Payment / batch status changes
* ACK/NACK availability notifications
* Exception alerts
* Sandbox test progress

WebSocket is an **entry point for outbound-to-partner push** and optional **inbound commands** (e.g. status subscription, ping). Transaction **submission** still typically uses HTTP or SFTP; WebSocket complements sync channels.

### 5.2 `connection_params` (WEBSOCKET)

```json
{
  "wsPath": "/v1/ws/partners/acme",
  "subprotocols": ["h2h.v1"],
  "heartbeatIntervalMs": 30000,
  "maxConnectionsPerPartner": 10,
  "authMode": "JWT_HANDSHAKE",
  "authRef": "vault:secret/partners/acme/ws-jwt",
  "allowedOrigins": ["https://erp.acme.com"],
  "maxMessageBytes": 65536,
  "sessionTimeoutMs": 300000
}
```

### 5.3 `websocket_subscription` (database-driven)

Which events are pushed to connected sessions — not hardcoded topics.

| Column              | Description                                                |
| ------------------- | ---------------------------------------------------------- |
| `subscription_id`   | UUID                                                       |
| `partner_id`        | FK                                                         |
| `channel_id`        | FK → `channel_config` (WEBSOCKET)                          |
| `event_code`        | FK → `event_def` — e.g. `PAYMENT_POSTED`, `FILE_DELIVERED` |
| `filter_expression` | JSONata on event payload                                   |
| `message_format`    | `JSON`, `ISO20022_CAMT054` (via transform\_spec)           |
| `enabled`           | Boolean                                                    |

On `event_code` fire → `EventWebSocketDispatcher` resolves subscriptions → pushes to active sessions for `partner_id`.

### 5.4 Flow

```mermaid
sequenceDiagram
  participant P as Partner browser/ERP
  participant WS as WebSocket Gateway
  participant Auth as Keycloak / JWT
  participant RT as h2h-runtime
  participant Bus as Event backbone

  P->>WS: WSS connect + token
  WS->>Auth: validate handshake
  WS->>RT: register session (partner_id)
  RT-->>P: connected + subscription ack

  Note over RT,Bus: Payment completes via HTTP/SFTP
  Bus->>RT: PAYMENT_POSTED event
  RT->>RT: websocket_subscription match
  RT->>P: push status JSON
```

### 5.5 Implementation

| Layer            | Technology                                                    |
| ---------------- | ------------------------------------------------------------- |
| WebSocket server | Spring WebFlux WebSocket, Camel `undertow`, or Kong WebSocket |
| Session registry | Redis or in-memory + sticky sessions                          |
| Event binding    | `h2h-event-extensions` → `WebSocketPushHandler`               |
| Auth             | JWT at handshake; mTLS at load balancer optional              |

**Module:** `h2h-websocket-ingress`

**Envelope (push message):**

```json
{
  "type": "PAYMENT_POSTED",
  "correlationId": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-06-30T12:00:00Z",
  "payload": { }
}
```

***

## 6. Other Entry Points (summary)

| Type       | Doc                                      | Notes                                         |
| ---------- | ---------------------------------------- | --------------------------------------------- |
| SFTP       | [15](/docs/15-file-management-system.md) | Poll/trigger via broker-delayed jobs optional |
| MQ         | [28](/docs/28-mq-jms-adapter.md)         | `channel_type: MQ`                            |
| Signed URL | [15](/docs/15-file-management-system.md) | `channel_type: SIGNED_URL`                    |

***

## 7. Convergence Model

All entry points:

1. Resolve `integration_profile` from `channel_config` + message type
2. Build `H2hContext` with `correlationId`, `partnerId`, `channelType`
3. Execute same `route_template` steps
4. Emit events via `EventPublisher` (`event_code` — [46](/docs/46-database-driven-events.md))
5. Audit via `h2h-observability`

| Entry point | Typical STP mode | Response to partner              |
| ----------- | ---------------- | -------------------------------- |
| HTTP        | Sync             | HTTP status + body               |
| WebSocket   | Async push       | WS frame (status/ACK)            |
| SFTP        | Async            | ACK file to outbox               |
| MQ          | Async            | Reply queue / correlation        |
| Signed URL  | Async            | Notification via HTTP/WS/webhook |

***

## 8. Security (all entry points)

| Control    | HTTP                        | WebSocket            | SFTP            | MQ                 |
| ---------- | --------------------------- | -------------------- | --------------- | ------------------ |
| TLS        | Required                    | WSS required         | SSH             | Channel encryption |
| Auth       | mTLS, OAuth2, API key, HMAC | JWT handshake, mTLS  | SSH key         | MQ credentials     |
| Rate limit | Gateway tier                | Connection + msg/sec | Poll interval   | Consumer prefetch  |
| Secrets    | Vault refs only             | Vault refs only      | Vault refs only | Vault refs only    |

See [09 Security and Compliance](/docs/09-security-and-compliance.md), [16 Security Library](/docs/16-security-library.md).

***

## 9. Admin Portal

| Screen           | Capability                                             |
| ---------------- | ------------------------------------------------------ |
| Channel wizard   | Select type: SFTP / HTTP / WebSocket / MQ / Signed URL |
| HTTP config      | Paths, methods, auth, rate tier, SOAP WSDL             |
| WebSocket config | WS path, origins, heartbeat, subscriptions             |
| Test harness     | Send sample HTTP request; connect test WS client       |
| Channel health   | Per-partner ingress status                             |

***

## 10. Deployment

| Component        | Deployable                                                                    |
| ---------------- | ----------------------------------------------------------------------------- |
| HTTP (REST/SOAP) | API gateway + `h2h-runtime`                                                   |
| WebSocket        | `h2h-websocket-ingress` in runtime or dedicated `h2h-ws-gateway` pod at scale |
| SFTP             | `h2h-file-gateway` or embedded file-management                                |

See [38 Deployment Topology](/docs/38-deployment-topology.md).

***

## 11. Related Documents

* [01 Architecture Overview](/docs/01-architecture-overview.md)
* [04 Database-Driven Configuration](/docs/04-database-driven-configuration.md)
* [08 Camel Integration Patterns](/docs/08-camel-integration-patterns.md)
* [39 API Gateway Architecture](/docs/39-api-gateway-architecture.md)
* [46 Database-Driven Events](/docs/46-database-driven-events.md)
* [37 Partner Portal](/docs/37-partner-portal.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://host2host.onibonje.com/docs/47-gateway-entrypoints.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.