[Proposal][Devportal] Gateway Integration via Outbound Webhooks

[Piumal1999]

Problem statement

The standalone developer portal can host APIs from multiple gateways simultaneously. A single portal may expose APIs running on WSO2 API Platform, Kong, AWS API Gateway, or any custom gateway at the same time. Regardless of where an API is deployed, the consumption experience for devportal users must be consistent: browse APIs, subscribe, generate keys, and manage applications through the same UI and API surface.

For this to work correctly, each gateway must be properly updated internally when a user takes an action. For example, when an api-key is generated, the relevant gateway needs to register it for future validations. When a subscription is created or a plan changes, the gateway needs to apply the corresponding enforcement rules.

The core challenge: the devportal does not know where an API is deployed, what gateway software is running, or how that gateway stores its configuration. It only knows an API's gateway_type, a string label like "wso2/api-platform" or "wso2/cloud-gateway".

---

Two approaches considered

Option 1: Gateway adapters

Write a plugin/adapter inside the devportal for each supported gateway. When a user generates a key, the devportal calls the adapter, which calls the gateway's admin API.

flowchart LR
    DP[devportal] --> W[adapter - WSO2] --> WA[WSO2 Admin API]
    DP --> K[adapter - Kong] --> KA[Kong Admin API]
    DP --> A[adapter - AWS] --> AA[AWS API GW API]

Loading

Why we rejected this:

Problem	Detail
Devportal knows too much	It must store gateway URLs, admin credentials, and understand each gateway's API contract. This couples the devportal to every gateway it supports.
Unbounded scope	Every new gateway requires devportal code changes for the related adapter
Credential sprawl	Admin credentials for every gateway live in the devportal's config, increasing the blast radius of a compromise.
Tight coupling	A gateway outage blocks the user action. If the WSO2 gateway API is down, key generation fails for all WSO2-backed APIs, even though the devportal itself is healthy.
Impedance mismatch	Devportal concepts (subscription, policy, key) don't map cleanly to every gateway's model. Adapters end up full of translation logic that is fragile and hard to test.

Option 2: Outbound webhooks (chosen)

The devportal fires events. Gateways subscribe and handle them however they need to.

flowchart LR
    DP["devportal"] -->|signed event| GA["gateway A handler"]
    DP -->|signed event| GB["gateway B handler"]
    DP -->|signed event| GC["gateway C handler"]

Loading

Why this is better:

Property	Benefit
Devportal stays generic	It only knows an event happened. It doesn't know what the gateway does with it.
Gateways own their logic	Each gateway team writes their own handler, in their own language, deployed in their own infrastructure. No devportal changes needed.
New gateways are free	Any system that can receive an HTTPS POST and verify a signature can integrate. Zero devportal code required.
Resilience	User actions succeed as soon as the devportal commits. Gateway sync happens async. A gateway outage causes retries, not user-facing errors.
No gateway credentials in devportal	The devportal only holds a shared HMAC secret and the gateway's public key. No admin credentials.
Auditable	Every event and every delivery attempt is persisted. Ops teams can inspect failures, replay events, and see exactly what was sent and when.

The key insight: the devportal is the source of truth. Gateways are consumers of that truth. The right pattern for distributing truth to multiple consumers is events, not direct API calls.

---

Architecture

High-level flow

flowchart TD

%% ======================
%% User
%% ======================
U["User"]

%% ======================
%% Developer Portal
%% ======================
subgraph DP["Developer Portal"]

    API["Devportal REST APIs"]

    Core["Devportal Core"]

    DB["Devportal DB (api_keys, subscriptions, DP_EVENT outbox)"]

    Registry["Subscriber Registry (config)"]

    Dispatcher["Event Dispatcher (poll pending, match subscribers, create deliveries)"]

    Worker["Delivery Worker (HMAC sign, HTTP POST, retry, backoff, dead-letter)"]
end

%% ======================
%% Gateways
%% ======================
subgraph G["Gateways"]

    GA["Gateway A (verify signature, decrypt key, store key)"]

    GB["Gateway B (verify signature, update quota rules)"]

    GC["Gateway C (verify signature, enforce plan, store key)"]
end

%% ======================
%% Relationships with actions
%% ======================

U -->|"invoke API (create key / subscribe / update plan)"| API

API -->|"call business logic"| Core

Core -->|"persist state + emit outbox event"| DB

API -->|"return response to user"| U

Core -->|"publish pending events"| Dispatcher

Dispatcher -->|"read pending events from outbox"| DB

Registry -->|"resolve gateway subscriptions by event type"| Dispatcher

Dispatcher -->|"create delivery tasks per subscriber"| Worker

Worker -->|"send signed webhook event"| GA
Worker -->|"send signed webhook event"| GB
Worker -->|"send signed webhook event"| GC

Loading

Sequence Diagram

sequenceDiagram
    autonumber

    participant U as User
    participant C as Devportal Core
    participant D as Event Dispatcher
    participant W as Delivery Worker
    participant G as Gateway

    U->>C: Generate key / Subscribe / Update plan

    C->>D: Emit domain event
    C-->>U: 200 OK

    D->>D: Process event
    D->>W: Create delivery tasks

    W->>G: HTTPS webhook (signed event)
    G-->>W: Response (success / failure)

    Note over W,G: Retry with backoff on failure

    G->>G: Apply changes (keys, subscriptions, policies)

Loading

Data model

DP_API_KEY: Devportal-owned key identity. Stores metadata only; the secret is never written to the database.

Column	Type	Notes
KEY_ID	UUID	PK
API_ID	UUID	FK → DP_API_METADATA
SUBSCRIPTION_ID	UUID	FK → DP_API_SUBSCRIPTION (nullable)
ORG_ID	UUID
NAME	VARCHAR(128)
STATUS	ENUM	ACTIVE, REVOKED
EXPIRES_AT	TIMESTAMP	nullable
CREATED_BY	VARCHAR
CREATED_AT	TIMESTAMP
REVOKED_AT	TIMESTAMP	nullable

DP_EVENT: The outbox. One row per domain event.

Column	Type	Notes
EVENT_ID	UUID	PK
EVENT_TYPE	VARCHAR(128)	e.g. apikey.generated
ORG_ID	UUID
GATEWAY_TYPE	VARCHAR(128)	routing hint (nullable)
AGGREGATE_TYPE	VARCHAR(64)	e.g. apikey, subscription
AGGREGATE_ID	UUID	PK of the primary entity
PAYLOAD	JSONB	event data (never contains plaintext key secrets)
OCCURRED_AT	TIMESTAMP
STATUS	ENUM	PENDING, DISPATCHED, ALL_DELIVERED, FAILED

DP_EVENT_DELIVERY: One row per (event x subscriber). Tracks each delivery attempt independently.

Column	Type	Notes
DELIVERY_ID	UUID	PK
EVENT_ID	UUID	FK → DP_EVENT
SUBSCRIBER_ID	VARCHAR(128)	matches config.yaml subscriber id
TARGET_URL	TEXT
ENCRYPTED_FIELDS	JSONB	per-subscriber ciphertext (apikey.* only)
STATUS	ENUM	PENDING, IN_FLIGHT, DELIVERED, FAILED, DEAD_LETTERED
ATTEMPT_COUNT	INTEGER
NEXT_ATTEMPT_AT	TIMESTAMP
LAST_HTTP_STATUS	INTEGER
LAST_ERROR	TEXT
LAST_ATTEMPT_AT	TIMESTAMP
DELIVERED_AT	TIMESTAMP

---

Design decisions

Transactional outbox

The event row is written in the same database transaction as the domain change. This eliminates the dual-write problem: if the domain write commits, the event commits with it. If the transaction rolls back, no phantom event is fired. User actions return immediately after the commit — gateway delivery happens asynchronously.

API keys are generated by the devportal, never stored

The devportal generates the key secret, encrypts it immediately per-subscriber using hybrid encryption (AES-256-GCM + RSA-OAEP), and stores only the ciphertext in the delivery row. The plaintext is returned to the user once and never written to any database column. Each gateway decrypts using its own RSA private key, so even a full database compromise does not expose key secrets.

Request signing

Every outbound webhook request is signed with HMAC-SHA256 using a per-subscriber shared secret. A timestamp included in the signature prevents replay attacks. Gateways verify the signature before processing any event.

At-least-once delivery with independent fan-out

Each subscriber gets its own delivery row, retried independently with exponential backoff. A slow or unavailable gateway does not block delivery to other subscribers. Deliveries that consistently fail are dead-lettered and can be retried via admin API.

Subscriber registration via config

Gateway subscribers are declared in config.yaml. This keeps configuration auditable in version control without requiring a database-backed registry or admin UI. A dynamic registry can be introduced later without changing the event pipeline.

---

Event catalog

Event	When fired
subscription.created	User subscribes to an API
subscription.deleted	User unsubscribes or admin deletes subscription
subscription.plan_changed	User switches subscription plan (Currently not supported in the UI)
apikey.generated	User generates a new API key
apikey.regenerated	User regenerates an existing key
apikey.revoked	User revokes a key

Out of scope for v1 (can be added without infrastructure changes): application.* events, OAuth token events.

---

Future work

• DB-backed subscriber registry: allow gateway webhook subscriptions to be managed at runtime via API without a devportal redeploy.
• Delivery metrics/analytics: expose counters for delivery success/failure rates per subscriber.
• Event schema versioning: add a schema_version field to the event envelope for forward compatibility.

[Piumal1999]

Related design doc is available at [1].

https://docs.google.com/document/d/1d8XZjPn_jEprxBhowJ5FiNVupKekrToNHYG6FPYyppI/edit?tab=t.0#heading=h.u0820ityif40