[Discussion] Platform API Webhook Event Handling

[DinithHerath]

Problem Statement

The Platform API currently has no dedicated path for handling webhook events emitted by other platform components when they perform an operation asynchronously. When a component such as Developer Portal or Management Portal performs an operation, the API Platform needs to become aware of that operation later and update its own state accordingly.

Examples:

• An API key is generated, regenerated, or revoked in Developer Portal.
• A subscription is created, changed, or deleted in Developer Portal.

The original proposal[1] placed this webhook-handling responsibility on the Gateway Controller. That design assumed Gateway holds and serves the authoritative API-key / subscription state directly to the policy engine, and that Gateway should be reachable by Developer Portal.

In our deployment topology we do not ship a combined Developer Portal + Gateway solution. Platform API is the control plane that already owns API-key and subscription state and already synchronizes that state to all Gateway replicas through an existing EventHub + WebSocket mechanism. Pointing Developer Portal at every Gateway and re-implementing persistence, signature verification, idempotency, and replica fan-out inside the Gateway would duplicate logic that Platform API already provides.

This revised proposal therefore implements the webhook endpoint in Platform API instead of the Gateway. Gateway state is updated as a downstream effect of Platform API's normal control-plane synchronization, with no Gateway-side webhook endpoint required.

Relationship to the Developer Portal webhook design

This document is the receiver-side counterpart to the Developer Portal producer-side design in [2]. In that design the Developer Portal is the source of truth: it commits a domain change, writes an event to a transactional outbox, and asynchronously delivers signed webhooks to a control-plane webhook receiver per gateway_type. The portal never talks to a gateway data plane directly.

Platform API is the receiver registered for gateway_type = "wso2/api-platform". Its job is to verify, decrypt, persist, and reconcile — and then propagate to its own gateway fleet using the control-plane sync it already owns. The contracts below (envelope, HMAC signing, hybrid encryption of secrets, at-least-once delivery) are fixed by the producer design; this document specifies how Platform API fulfills them.

Scope

This effort focuses on the Platform API-side webhook implementation.

The first set of supported event families:

• API key events
  • apikey.generated
  • apikey.regenerated
  • apikey.revoked
• Subscription events
  • subscription.created
  • subscription.plan_changed
  • subscription.deleted

Why Platform API instead of Gateway

Concern	Gateway-hosted webhook (original)	Platform API-hosted webhook (this proposal)
Owner of API key / subscription state	Gateway storage	Platform API DB (already authoritative)
Who Developer Portal must reach	Every Gateway instance	A single control-plane endpoint
Gateway state refresh	Gateway refreshes its own xDS snapshot directly	Platform API publishes through the existing EventHub → WebSocket sync; all Gateway replicas converge automatically
Signature verification, idempotency, decryption	New code in Gateway Controller	Reuses Platform API crypto, repository, and event infrastructure
Replica fan-out	New Gateway-internal EventHub event	Existing gateway_events delivery; no new fan-out path

The net effect: the webhook handler only needs to validate the event and apply the domain change to Platform API storage. Propagation to Gateways is an existing, already-tested capability.

Proposal

• Introduce a webhook endpoint in Platform API. External platform components (Developer Portal / Management Portal) send signed HTTP POST requests to this endpoint. Platform API will verify the request, decode the common event envelope, check idempotency, and dispatch the event to the matching event handler.
• The webhook endpoint is not a normal management API. A normal API request commands Platform API to perform an operation. A webhook event informs Platform API that an operation has already happened somewhere else, and Platform API should reconcile its local state.
• After the domain change is persisted, Platform API publishes the corresponding internal event through the existing GatewayEventsService (EventHub). Connected Gateway replicas receive it over their WebSocket control connection and update their own state and xDS snapshots — exactly as they do today for api.deployed, apikey.*, and subscription.* events.

High-Level Flow

sequenceDiagram
participant DP as Developer Portal / Management Portal
participant WH as Platform API Webhook Endpoint
participant REG as Event Handler Registry
participant H as Event Handler
participant DB as Platform API DB
participant EH as EventHub (GatewayEventsService)
participant GW as Gateway Replicas

DP->>WH: POST /api/internal/v1/webhook/events with signed event
WH->>WH: Read raw body (size limited)
WH->>WH: Verify HMAC signature
WH->>WH: Decode common event envelope
WH->>WH: Check gateway_type
WH->>WH: Check event_id idempotency
WH->>REG: Dispatch by event_type
REG->>H: Invoke matching handler
H->>DB: Persist / upsert domain state
H->>EH: Publish internal event (apikey.* / subscription.*)
EH->>GW: Deliver over existing WebSocket sync
GW->>GW: Refresh local state + xDS snapshot
WH->>DP: Return 2xx when accepted

Loading

Webhook Endpoint

• Endpoint: POST /api/internal/v1/webhook/events
  • Registered alongside the other internal/control-plane routes in Platform API (the same group that hosts gateway connection and internal sync routes), outside the JWT/IDP auth middleware. Authenticity is established by HMAC signature, not by the platform auth chain.
• Endpoint registration must be configurable (the route is only registered when webhook.enabled = true).

[webhook]
enabled = true
secret = "5f74be8fdd5450a9793af3962f56da27f7de3f64263d73f739e9223f27cb1fd4"
private_key_path = "/app/certificates/devportal-webhook.pem"
gateway_type = "wso2/api-platform"
signature_tolerance = "5m"
max_body_size = "1MiB"

Configuration options

• enabled - controls whether the webhook endpoint is registered.
• secret - the HMAC signing secret shared with the event producer (Developer Portal).
• private_key_path - points to the Platform API private key used to decrypt encrypted sensitive payload fields.
• gateway_type - used to filter events meant for this platform type.
• signature_tolerance - prevents replay attacks using old signed requests.
• max_body_size - protects the endpoint from unexpectedly large request bodies.

Configuration is loaded via the existing koanf-based loader (src/config/config.go) with env-var overrides (e.g. WEBHOOK_ENABLED, WEBHOOK_SECRET). The secret and private_key_path should be sourced from env/secret mounts in production rather than committed TOML.

Event Envelope

All webhook events share a common envelope. It mirrors the Developer Portal DP_EVENT outbox row (event_id, event_type, org_id, gateway_type, aggregate_type, aggregate_id, data/payload, occurred_at):

{
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_type": "apikey.generated",
  "occurred_at": "2026-04-24T10:00:00.000Z",
  "org_id": "org-uuid",
  "gateway_type": "wso2/api-platform",
  "aggregate_type": "apikey",
  "aggregate_id": "domain-object-id",
  "schema_version": "1.0",
  "data": {}
}

• event_id - unique per event; used for idempotency.
• org_id - resolves to the Platform API organization context (replaces the JWT-derived org context used by normal APIs).
• gateway_type - routing hint set by the producer. Platform API processes the event only when it matches the configured gateway_type; otherwise the event is a no-op (202).
• aggregate_type - the kind of domain object affected (apikey, subscription), used to select the handler family alongside event_type.
• aggregate_id - stable domain object ID affected by the event. Included for events where the affected domain object must be identified even when event-specific fields are missing or change later.
• schema_version - envelope version for forward compatibility. This is forward-compat/optional: the Developer Portal lists it as planned work, so Platform API must tolerate its absence and treat a missing value as the current 1.0 schema rather than rejecting the event.

Security Model

Webhook security has two separate responsibilities:

1. Request authenticity & integrity
2. Sensitive data confidentiality

Signature Verification

• The Developer Portal signs every outbound request with HMAC-SHA256 using the per-subscriber shared secret it holds for the Platform API receiver. On the Platform API side this is the configured secret.
• Each webhook request must include an HMAC-SHA256 signature header.
  • Example: X-Devportal-Signature: t=1713952800,v1=<calculated_hmac>
• The signature is calculated over the raw request body:

signed_payload = "<timestamp>.<raw_body>"
signature      = HMAC-SHA256(secret, signed_payload)

• Platform API verifies the request as follows:
  1. Read the raw request body with the configured maximum size (max_body_size).
  2. Extract t and v1 from the signature header.
  3. Reject the request if the timestamp is outside the configured tolerance (signature_tolerance).
  4. Compute the expected HMAC using the shared secret.
  5. Compare expected and received signatures using a timing-safe comparison (hmac.Equal / crypto/subtle).
  6. Reject the request if verification fails.

Sensitive Data Decryption

• Some events carry sensitive values such as API keys or subscription tokens. These must not be transmitted in plaintext.
• Per the producer design, the Developer Portal generates the secret, encrypts it once per receiver using hybrid encryption (AES-256-GCM + RSA-OAEP), and stores only the ciphertext in its delivery row — it never persists the plaintext. The secret reaches Platform API only inside the encrypted field:

{
  "encrypted_key": {
    "wrappedKey": "<base64>",   // AES content key, RSA-OAEP-wrapped with Platform API's public key
    "iv": "<base64>",           // AES-GCM nonce
    "tag": "<base64>",          // AES-GCM auth tag
    "ciphertext": "<base64>"    // AES-GCM-encrypted secret
  }
}

• Decryption is therefore two stages, using Platform API's configured RSA private key (private_key_path):
  1. RSA-OAEP unwrap wrappedKey to recover the one-time AES-256 content key.
  2. AES-256-GCM decrypt ciphertext with that key, iv, and tag.
• The existing AES-256-GCM helper in src/internal/utils/subscription_token_crypto.go covers stage 2 (the symmetric half) and the API-key hashing rules in src/internal/service/apikey.go cover deriving the stored representation. The RSA-OAEP unwrap (stage 1) and PEM private-key loading are new code — crypto/rsa + crypto/x509 — since the current utilities only handle a symmetric key derived from config, not an RSA-wrapped per-event key.
• Note: The decrypted secret must only be held in memory long enough to derive the required Platform API representation (such as a hash). It must not be logged or persisted in plaintext. Because the producer also never stores it, the plaintext secret exists only transiently end-to-end.

HTTP Processing Flow

flowchart TD
A[POST /api/internal/v1/webhook/events] --> B{Webhook enabled?}
B -- No --> C[404]
B -- Yes --> D[Read raw body with size limit]
D --> E{Signature valid?}
E -- No --> F[401 Unauthorized]
E -- Yes --> G[Decode event envelope]
G --> H{Envelope valid?}
H -- No --> I[400 Bad Request]
H -- Yes --> J{gateway_type matches?}
J -- No --> K[202 Accepted as no-op]
J -- Yes --> L{Dispatch by event_type}
L --> M[Apply event-specific DB idempotency check]
M --> N{Domain state already persisted?}
N -- Yes --> O[Skip duplicate DB write]
N -- No --> P[Persist domain state]
O --> Q[Publish EventHub event via GatewayEventsService]
P --> Q
Q --> R{Publish successful?}
R -- No --> S[500 Retryable failure]
R -- Yes --> T[200 OK / 202 Accepted]

Loading

Note: unlike the Gateway-hosted design, there is no in-handler xDS refresh step. Once the event is published through GatewayEventsService, Gateway replicas refresh their own state and xDS snapshots asynchronously over the existing WebSocket sync. The webhook response reflects that Platform API has durably accepted and published the change.

Webhook vs Normal Platform API

Area	Normal Platform API	Webhook Endpoint
Purpose	Command Platform API to perform an operation	Notify Platform API of an operation that already happened
Caller	Client, CLI, UI, or CP	Trusted platform components such as Developer Portal
Auth	JWT / IDP-based (scope-enforced)	HMAC signature with shared secret
Org context	Derived from JWT	Derived from org_id in the envelope
Processing model	Usually synchronous	Asynchronous event handling
Idempotency	Useful but not always mandatory	Required; retry/duplicate deliveries are expected
Consistency model	Request–response consistency	Eventual consistency (Gateways converge via sync)
Extension model	Add new API operation	Add new event handler

Suggested Package Structure

Mirrors the existing Platform API layout (handler → service → repository → model):

As built (see platform-api-webhook-implementation.md §2 for the authoritative map):

platform-api/src/internal/webhook/
  envelope.go               # common envelope decode + validation; EncryptedKey
  verifier.go               # HMAC signature verification
  decryptor.go              # RSA-OAEP unwrap + AES-256-GCM decrypt; PEM key loading
  errors.go                 # sentinel errors
  receiver.go               # gin handler: flow, dispatch table, error->status, service interfaces
  handlers_apikey.go        # apikey.* handlers (reuse APIKeyService)
  handlers_subscription.go  # subscription.* handlers (reuse SubscriptionService)
  ...

Handlers depend on the existing services/repositories rather than introducing a parallel persistence layer:

• apikey handler → APIKeyRepository (api_keys table) + GatewayEventsService (apikey.* events).
• subscription handler → SubscriptionRepository (subscriptions table) + GatewayEventsService (subscription.* events).

API Key Event Handling

Supported Events

Event	Meaning
apikey.generated	A new API key was generated for an API outside Platform API.
apikey.regenerated	An existing API key was rotated outside Platform API.
apikey.revoked	An API key was revoked outside Platform API.

API Key Generation Event Payload

{
  "event_id": "event-uuid",
  "event_type": "apikey.generated",
  "occurred_at": "2026-04-24T10:00:00.000Z",
  "org_id": "org-uuid",
  "gateway_type": "wso2/api-platform",
  "schema_version": "1.0",
  "aggregate_id": "key-uuid",
  "data": {
    "key_id": "key-uuid",
    "name": "my-key",
    "expires_at": "2027-01-01T00:00:00.000Z",
    "api": {
      "ref_id": "api-handle",
      "name": "Order API",
      "version": "1.0.0"
    },
    "subscription": {
      "ref_id": "subscription-uuid",
      "plan_name": "Gold"
    },
    "encrypted_key": {
      "wrappedKey": "<base64>",
      "iv": "<base64>",
      "tag": "<base64>",
      "ciphertext": "<base64>"
    }
  }
}

API Key Revoke / Regenerate Event Payload

{
  "event_id": "event-uuid",
  "event_type": "apikey.revoked",
  "occurred_at": "2026-04-24T10:00:00.000Z",
  "org_id": "org-uuid",
  "gateway_type": "wso2/api-platform",
  "schema_version": "1.0",
  "aggregate_id": "key-uuid",
  "data": {
    "key_id": "key-uuid",
    "name": "my-key",
    "api": {
      "name": "MyFlights API",
      "version": "1.0.0",
      "ref_id": "api_handle"
    }
  }
}

(apikey.regenerated uses the same shape.)

• data.key_id is mapped to an external reference on the api_keys record, used to:
  • identify whether the API key already exists when an apikey.generated event is received (idempotency);
  • select the correct API key when an apikey.regenerated or apikey.revoked event is received.

API Reference Resolution

• data.api.ref_id resolves to the Platform API artifact / API record via APIRepository.
• The handler uses the resolved API UUID together with org_id to locate the API-key record.

API Key Generation Flow

1. Resolve the API using data.api.ref_id.
2. Decrypt data.encrypted_key.
3. Hash the decrypted key using the existing Platform API API-key hashing rules (api_key.hashing_algorithms).
4. Clear the plaintext secret from memory as soon as possible.
5. Persist or upsert the API key in the api_keys table (keyed by key_id / external ref + org).
6. Publish an apikey.created (and analogous) event via GatewayEventsService.
7. Connected Gateway replicas receive the event and update their local API-key state and xDS snapshots.

API Key Regeneration / Revoke

The flow mirrors generation but uses data.key_id to locate the exact API-key record, then upserts the new hash (regenerate) or marks it revoked (revoke), and publishes the corresponding apikey.updated / apikey.revoked event.

Subscription Event Handling

Supported Events

Event	Meaning
subscription.created	A subscription was created outside Platform API.
subscription.plan_changed	A subscription plan was changed outside Platform API.
subscription.deleted	A subscription was deleted outside Platform API.

Subscription Creation Event Payload

{
  "event_id": "event-uuid",
  "event_type": "subscription.created",
  "occurred_at": "2026-04-24T10:00:00.000Z",
  "org_id": "org-uuid",
  "gateway_type": "wso2/api-platform",
  "schema_version": "1.0",
  "aggregate_id": "subscription-uuid",
  "data": {
    "subscription_plan": {
      "ref_id": "subscription_plan_name",
      "status": "ACTIVE"
    },
    "api": {
      "ref_id": "api_handle",
      "name": "Order API",
      "version": "1.0.0"
    },
    "encrypted_key": {
      "wrappedKey": "<base64>",
      "iv": "<base64>",
      "tag": "<base64>",
      "ciphertext": "<base64>"
    }
  }
}

Subscription Deletion / Plan Change Event Payload

{
  "event_id": "event-uuid",
  "event_type": "subscription.deleted",
  "occurred_at": "2026-04-24T10:00:00.000Z",
  "org_id": "org-uuid",
  "gateway_type": "wso2/api-platform",
  "schema_version": "1.0",
  "aggregate_id": "subscription-uuid",
  "data": {
    "subscription_plan": {
      "ref_id": "subscription_plan_name",
      "plan_name": "Gold",
      "status": "ACTIVE"
    },
    "api": {
      "name": "MyFlights API",
      "version": "1.0.0",
      "ref_id": "api_handle"
    }
  }
}

Subscription Reference Resolution

• data.api.ref_id resolves to the Platform API API UUID.
• data.subscription_plan.ref_id resolves to the subscription-plan UUID for the given org_id (org + plan name is unique).
• Both UUIDs together identify the subscription record in the subscriptions table.

Subscription Creation Flow

1. Resolve the API using data.api.ref_id.
2. Resolve the subscription plan using data.subscription_plan.ref_id.
3. Decrypt the subscription token from data.encrypted_key.
4. Hash the token (reuse subscription_token_hash derivation).
5. Resolve the API and subscription-plan UUIDs from the ref_ids.
6. Check whether a subscription with those UUIDs already exists; skip persistence if so (idempotency).
7. Persist or upsert the subscription as ACTIVE.
8. Publish a subscription.created event via GatewayEventsService.
9. Gateway replicas refresh their subscription state and xDS snapshots over the existing sync.

Subscription Plan Change / Delete

Same flow, using the resolved ref_ids to locate the subscription, then updating the plan (subscription.updated) or marking it deleted/revoked (subscription.deleted), and publishing the corresponding event.

Persistence and State Update Order

flowchart LR
A[Validate event] --> B[Apply domain change to Platform API DB]
B --> C[Publish EventHub event via GatewayEventsService]
C --> D[Mark webhook event as processed]
D --> E[Gateways converge asynchronously via WebSocket sync]

Loading

The webhook handler's responsibility ends at publishing through EventHub. Gateway-side convergence is decoupled and handled by the existing control-plane delivery, which already guarantees replica fan-out and reconnect/replay semantics.

Idempotency

• The producer guarantees at-least-once delivery: each receiver has its own delivery row that the Developer Portal retries independently with exponential backoff, and dead-letters after repeated failure. The same event_id will therefore be redelivered whenever Platform API does not return a success status (timeout, 5xx, or a success that the producer never received). Platform API must handle duplicate deliveries safely — idempotency is mandatory, not optional.
• As built, idempotency is handled entirely at the domain level — there is no separate processed-event table. Each event handler checks whether the requested domain change has already been applied (an API key with the same (api, name) already exists, or a subscription with the same API + subscriber already exists) and treats that as success. A duplicate delivery is therefore always a safe 200.
• An earlier draft proposed an additional envelope-level event_id ledger to short-circuit exact replays before re-running the handler. That was dropped to minimize moving parts: it is an optimization (skip rework, suppress redundant gateway re-broadcasts), not a correctness requirement, and it could only ever be best-effort since the reused services commit the domain change and publish to the EventHub in separate transactions. The trade-off is that each duplicate re-runs the handler and re-broadcasts to gateways (same end state, redundant work). Reintroduce the ledger if duplicate-driven broadcast load becomes a concern. See platform-api-webhook-implementation.md §5/§8.

sequenceDiagram
participant DP as Developer Portal
participant API as Platform API
participant DB as Platform API DB
participant EH as EventHub (GatewayEventsService)

DP->>API: POST event
API->>API: Verify signature and validate envelope
API->>DB: Check event-specific domain state
alt State not found
    API->>DB: Persist domain state
else State already exists
    API->>API: Skip duplicate DB write
end
API->>EH: Publish internal event
alt Publish fails
    API-->>DP: 500 Retryable failure
else Publish succeeds
    API-->>DP: 200 OK
end

Loading

EventHub & Replica / Gateway Synchronization

• After a webhook handler successfully updates Platform API storage, it publishes an internal event through the existing GatewayEventsService (src/internal/service/gateway_events.go).
• This is the same path Platform API already uses for api.deployed, apikey.*, and subscription.* events. Events are persisted to the events table and delivered to:
  • other Platform API replicas (HA), and
  • all connected Gateway replicas over their WebSocket control connection.
• Each Gateway replica then refreshes its local in-memory state and xDS snapshots. No new fan-out mechanism or Gateway-side webhook endpoint is introduced.

flowchart LR
A[External webhook event] --> B[Receiving Platform API replica]
B --> C[Update Platform API DB]
C --> D[Publish event via GatewayEventsService]
D --> E[Other Platform API replicas]
D --> F[Connected Gateway replicas]
F --> G[Refresh local state and xDS snapshots]

Loading

Error Handling

Case	Response	Notes
Webhook disabled	404	Endpoint not registered
Missing signature	401	Request is unauthenticated
Invalid signature	401	Do not reveal details
Timestamp outside tolerance	401	Possible replay
Invalid JSON	400	Bad Request
Missing required envelope field	400	Bad Request
Unsupported event type	400	Bad Request
Gateway type mismatch	202	Accepted as no-op
Duplicate processed event	200	Idempotent success
Temporary storage failure	500	Producer should retry
Temporary EventHub publish failure	500	Producer should retry

Summary of Changes from the Original Proposal([2])

• Endpoint owner: Gateway Controller → Platform API (POST /api/internal/v1/webhook/events).
• Persistence: Gateway storage → Platform API DB (existing api_keys / subscriptions tables and repositories).
• Gateway state refresh: in-handler xDS refresh → existing EventHub → WebSocket sync to Gateway replicas (no Gateway webhook endpoint, no new fan-out path).
• Reused infrastructure: koanf config, slog logging, AES-256-GCM crypto utils, API-key hashing, GatewayEventsService, and the repository/handler/service layering already present in Platform API.
• Unchanged: the common envelope, HMAC-SHA256 signature scheme, encrypted sensitive-field handling, idempotency requirements, and supported event families.

[1] #2099
[2] #1774