Using Integration Hub gRPC APIs

Goal

Use the Subscription Management service's gRPC and REST APIs to programmatically manage subscriptions and event definitions in Integration Hub.

Audience

Developers building automation, admin tooling, or services that need to dynamically manage Integration Hub subscriptions.

Prerequisites

Access to the Subscription Management service
gRPC client tooling (e.g., grpcurl) or HTTP client for REST calls
The subscription proto artifact for gRPC client generation (obtain from the internal artifact registry)

Before You Start

The Subscription Management service exposes two API surfaces for the same operations:

API	Protocol	Best For
gRPC	Protobuf over HTTP/2	Service-to-service communication, automated pipelines
REST	JSON over HTTP	Manual testing, admin tools, debugging

Both APIs share the same underlying service layer and data store. Choose the one that fits your use case.

Worked Example

In this guide, you create an event definition, register a subscription via gRPC, query it, update it, and clean up — covering the full subscription lifecycle.

Steps

1. Set up the gRPC client

Add the subscription proto artifact dependency to your project. Obtain the artifact coordinates from the internal artifact registry.

pom.xml
<dependency>
    <groupId>${subscription.proto.groupId}</groupId>
    <artifactId>${subscription.proto.artifactId}</artifactId>
    <version>${subscription.proto.version}</version>
</dependency>

Configure the gRPC client to connect to the Subscription Management service:

application.properties (example)
grpc.client.subscription-service.host=<SUBSCRIPTION_SERVICE_HOST>
grpc.client.subscription-service.port=<GRPC_PORT>

Inject the generated gRPC stub in your service class:

SubscriptionClient.java
public class SubscriptionClient {

    private final SubscriptionServiceGrpc.SubscriptionServiceStub grpcClient;

    public SubscriptionClient(ManagedChannel channel) {
        this.grpcClient = SubscriptionServiceGrpc.newStub(channel);
    }
}

2. Create an event definition

Before registering subscriptions, create the event type definition that represents the category of events your subscribers want to receive.

gRPC:

Create event via gRPC
SubscriptionEvent event = SubscriptionEvent.newBuilder()
    .setId(UUID.randomUUID().toString())
    .setSourceService("my-service")
    .setEventType("order.completed")
    .setResourceType("order")
    .setOperationType("CREATE")
    .build();

grpcClient.createSubscriptionEvent(event, responseObserver);

REST equivalent:

Create event via REST
curl -X POST https://<SUBSCRIPTION_SERVICE_HOST>/api/v1/events \
  -H "Content-Type: application/json" \
  -d '{
    "event": {
      "id": "22222222-2222-2222-2222-222222222222",
      "sourceService": "my-service",
      "eventType": "order.completed",
      "resourceType": "order",
      "operationType": "CREATE"
    }
  }'

SubscriptionEvent fields:

Field	Type	Required	Description
`id`	UUID	Yes	Unique identifier for the event definition
`source_service`	String	Yes	The upstream service producing this event type
`event_type`	String	Yes	Event type name (e.g., `user.created`, `order.completed`)
`resource_type`	String	Yes	The resource category affected
`operation_type`	String	Yes	The operation performed (`CREATE`, `UPDATE`, `DELETE`)

3. Create a subscription

gRPC:

Create subscription via gRPC
Subscription subscription = Subscription.newBuilder()
    .setId(UUID.randomUUID().toString())
    .setEventId("22222222-2222-2222-2222-222222222222")
    .setSubscriberService("order-notification-service")
    .setDeliveryEndpoint("https://notifications.example.com/webhooks/orders")
    .setCallbackProtocol(CallbackProtocol.CALLBACK_PROTOCOL_HTTP)
    .setRequestMethod(RequestMethod.REQUEST_POST)
    .setActive(true)
    .setPayloadType(PayloadType.PAYLOAD_TYPE_JSON)
    .setAuth(SubscriberAuth.newBuilder()
        .setType(SubscriberAuthType.AUTH_TYPE_APIKEY)
        .setApikey(ApiKeyAuth.newBuilder()
            .setHeaderName("X-API-KEY")
            .setKey("<YOUR_API_KEY>")
            .build())
        .build())
    .build();

grpcClient.createSubscription(subscription, responseObserver);

REST equivalent:

Create subscription via REST
curl -X POST https://<SUBSCRIPTION_SERVICE_HOST>/api/v1/subscriptions \
  -H "Content-Type: application/json" \
  -d '{
    "subscription": {
      "eventId": "22222222-2222-2222-2222-222222222222",
      "subscriberService": "order-notification-service",
      "deliveryEndpoint": "https://notifications.example.com/webhooks/orders",
      "callbackProtocol": "CALLBACK_PROTOCOL_HTTP",
      "requestMethod": "REQUEST_POST",
      "active": true,
      "payloadType": "PAYLOAD_TYPE_JSON",
      "auth": {
        "type": "AUTH_TYPE_APIKEY",
        "apikey": {
          "key": "<YOUR_API_KEY>",
          "headerName": "X-API-KEY"
        }
      }
    }
  }'

4. Query subscriptions

List all subscriptions (gRPC):

Get all subscriptions
grpcClient.getAllSubscriptions(Empty.getDefaultInstance(), responseObserver);

Get subscription by ID (gRPC):

Get by ID
IdRequest request = IdRequest.newBuilder()
    .setId("aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa")
    .build();

grpcClient.getSubscriptionById(request, responseObserver);

Get subscriptions by event criteria (gRPC):

Query by event criteria
SubscriptionsByEventRequest request = SubscriptionsByEventRequest.newBuilder()
    .setSourceService("my-service")
    .setEventType("order.completed")
    .setResourceType("order")
    .setOperationType("CREATE")
    .build();

grpcClient.getSubscriptionsByEvent(request, responseObserver);

REST equivalents:

REST query endpoints
# List all subscriptions
curl https://<SUBSCRIPTION_SERVICE_HOST>/api/v1/subscriptions

# Get subscription by ID
curl https://<SUBSCRIPTION_SERVICE_HOST>/api/v1/subscriptions/{id}

# Get subscriptions by event ID
curl https://<SUBSCRIPTION_SERVICE_HOST>/api/v1/subscriptions/event/{eventId}

# List all event definitions
curl https://<SUBSCRIPTION_SERVICE_HOST>/api/v1/events

# Get event definition by ID
curl https://<SUBSCRIPTION_SERVICE_HOST>/api/v1/events/{id}

5. Update a subscription

Update subscription properties such as the delivery endpoint, authentication, or active status.

gRPC:

Update subscription
Subscription updated = Subscription.newBuilder()
    .setId("existing-subscription-id")
    .setEventId("22222222-2222-2222-2222-222222222222")
    .setSubscriberService("order-notification-service")
    .setDeliveryEndpoint("https://new-endpoint.example.com/webhooks/orders")
    .setCallbackProtocol(CallbackProtocol.CALLBACK_PROTOCOL_HTTP)
    .setRequestMethod(RequestMethod.REQUEST_POST)
    .setActive(true)
    .setPayloadType(PayloadType.PAYLOAD_TYPE_JSON)
    .setAuth(SubscriberAuth.newBuilder()
        .setType(SubscriberAuthType.AUTH_TYPE_APIKEY)
        .setApikey(ApiKeyAuth.newBuilder()
            .setHeaderName("X-API-KEY")
            .setKey("<YOUR_NEW_API_KEY>")
            .build())
        .build())
    .build();

grpcClient.updateSubscription(updated, responseObserver);

REST equivalent:

Update subscription via REST
curl -X PUT https://<SUBSCRIPTION_SERVICE_HOST>/api/v1/subscriptions \
  -H "Content-Type: application/json" \
  -d '{
    "subscription": {
      "id": "existing-subscription-id",
      "eventId": "22222222-2222-2222-2222-222222222222",
      "subscriberService": "order-notification-service",
      "deliveryEndpoint": "https://new-endpoint.example.com/webhooks/orders",
      "callbackProtocol": "CALLBACK_PROTOCOL_HTTP",
      "requestMethod": "REQUEST_POST",
      "active": true,
      "payloadType": "PAYLOAD_TYPE_JSON",
      "auth": {
        "type": "AUTH_TYPE_APIKEY",
        "apikey": {
          "key": "<YOUR_NEW_API_KEY>",
          "headerName": "X-API-KEY"
        }
      }
    }
  }'

note

The update operation requires the subscription id in the request body. The service overwrites all fields — include the complete subscription object, not only the changed fields.

6. Delete a subscription

Remove a subscription when your service no longer needs to receive events.

gRPC:

Delete subscription
IdRequest request = IdRequest.newBuilder()
    .setId("subscription-id-to-delete")
    .build();

grpcClient.deleteSubscription(request, responseObserver);

REST equivalent:

Delete via REST
curl -X DELETE https://<SUBSCRIPTION_SERVICE_HOST>/api/v1/subscriptions/{id}

7. Verify with grpcurl (optional)

Use grpcurl for quick testing and debugging of the gRPC API:

grpcurl examples
# List all subscriptions
grpcurl -plaintext <SUBSCRIPTION_SERVICE_HOST>:<GRPC_PORT> \
  SubscriptionService/GetAllSubscriptions

# Get subscription by ID
grpcurl -plaintext -d '{"id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"}' \
  <SUBSCRIPTION_SERVICE_HOST>:<GRPC_PORT> \
  SubscriptionService/GetSubscriptionById

# Get subscriptions by event criteria
grpcurl -plaintext -d '{
  "source_service": "my-service",
  "event_type": "order.completed",
  "resource_type": "order",
  "operation_type": "CREATE"
}' <SUBSCRIPTION_SERVICE_HOST>:<GRPC_PORT> \
  SubscriptionService/GetSubscriptionsByEvent

gRPC API Reference

SubscriptionService Methods

Method	Request	Response	Description
`GetAllSubscriptions`	`Empty`	`SubscriptionsResponse`	List all subscriptions
`GetSubscriptionById`	`IdRequest`	`SubscriptionResponse`	Get a single subscription
`GetSubscriptionsByEvent`	`SubscriptionsByEventRequest`	`SubscriptionsByEventResponse`	Query by event criteria
`CreateSubscription`	`Subscription`	`Empty`	Create a new subscription
`UpdateSubscription`	`Subscription`	`Empty`	Update an existing subscription
`DeleteSubscription`	`IdRequest`	`Empty`	Delete a subscription
`CreateSubscriptionEvent`	`SubscriptionEvent`	`Empty`	Create an event definition
`GetSubscriptionEvents`	`Empty`	`EventsResponse`	List all event definitions
`GetSubscriptionEventById`	`IdRequest`	`EventResponse`	Get a single event definition
`UpdateSubscriptionEvent`	`SubscriptionEvent`	`Empty`	Update an event definition
`DeleteSubscriptionEvent`	`IdRequest`	`Empty`	Delete an event definition

REST API Reference

Method	Path	Description
`GET`	`/api/v1/subscriptions`	List subscriptions (with filters)
`GET`	`/api/v1/subscriptions/{id}`	Get subscription by ID
`GET`	`/api/v1/subscriptions/event/{id}`	Get subscriptions by event ID
`POST`	`/api/v1/subscriptions`	Create subscription
`PUT`	`/api/v1/subscriptions`	Update subscription
`DELETE`	`/api/v1/subscriptions/{id}`	Delete subscription
`GET`	`/api/v1/events`	List event definitions
`GET`	`/api/v1/events/{id}`	Get event definition by ID
`POST`	`/api/v1/events`	Create event definition
`PUT`	`/api/v1/events`	Update event definition
`DELETE`	`/api/v1/events/{id}`	Delete event definition

Proto Enum Values

CallbackProtocol:

Value	Description
`CALLBACK_PROTOCOL_GRPC`	gRPC callback
`CALLBACK_PROTOCOL_HTTP`	HTTP webhook (most common)
`CALLBACK_PROTOCOL_SOAP`	SOAP endpoint
`CALLBACK_PROTOCOL_WEBSOCKET`	WebSocket connection

RequestMethod:

Value	Description
`REQUEST_GET`	HTTP GET
`REQUEST_POST`	HTTP POST (default)
`REQUEST_PUT`	HTTP PUT
`REQUEST_DELETE`	HTTP DELETE
`REQUEST_HEAD`	HTTP HEAD
`REQUEST_OPTIONS`	HTTP OPTIONS
`REQUEST_TRACE`	HTTP TRACE

PayloadType:

Value	Description
`PAYLOAD_TYPE_JSON`	JSON payload (`Content-Type: application/json`)
`PAYLOAD_TYPE_PROTOBUF`	Raw Protobuf bytes

SubscriberAuthType:

Value	Description
`AUTH_TYPE_BASIC`	HTTP Basic Authentication
`AUTH_TYPE_OAUTH2`	OAuth2 token exchange
`AUTH_TYPE_JWT`	Bearer token (pre-shared)
`AUTH_TYPE_APIKEY`	Custom header API key

Validation Scenario

Scenario

You create an event definition and a subscription via gRPC, then verify the subscription is queryable.

Expected Result

The data store contains the event definition
The subscription exists with active = true
GetSubscriptionsByEvent returns the subscription when queried with matching event criteria

How to Verify

gRPC evidence: GetSubscriptionById returns the created subscription with all fields intact
REST evidence: GET /api/v1/subscriptions/{id} returns the same data
Logs: Subscription Management service logs show the request processing

Troubleshooting

INVALID_ARGUMENT gRPC error — A required field is missing or invalid. Check that eventId, subscriberService, deliveryEndpoint, and auth fields are all populated correctly.
Auth validation error — Each auth type has specific required fields: Basic needs username + password, OAuth2 needs clientId + clientSecret + tokenUrl + scope, JWT needs token, API Key needs key + headerName.
Subscription not matching events — The GetSubscriptionsByEvent query matches on sourceService, eventType, resourceType, and operationType. All four fields must match the producer's event criteria.

Next Steps

To add authorization checks to your service, see Using Access Gateway from Services.

Integration Hub Overview

Architecture and end-to-end event flow.

Consumer Model

Subscription registration and event type definitions.

gRPC Ingestion Surface

How events enter Integration Hub via gRPC.

Building Consumers

How to build a webhook endpoint for event delivery.

Goal​

Audience​

Prerequisites​

Before You Start​

Worked Example​

Steps​

1. Set up the gRPC client​

2. Create an event definition​

3. Create a subscription​

4. Query subscriptions​

5. Update a subscription​

6. Delete a subscription​

7. Verify with grpcurl (optional)​

gRPC API Reference​

SubscriptionService Methods​

REST API Reference​

Proto Enum Values​

Validation Scenario​

Scenario​

Expected Result​

How to Verify​

Troubleshooting​

Next Steps​

Related Docs​

Integration Hub Overview

Consumer Model

gRPC Ingestion Surface

Building Consumers

Goal

Audience

Prerequisites

Before You Start

Worked Example

Steps

1. Set up the gRPC client

2. Create an event definition

3. Create a subscription

4. Query subscriptions

5. Update a subscription

6. Delete a subscription

7. Verify with grpcurl (optional)

gRPC API Reference

SubscriptionService Methods

REST API Reference

Proto Enum Values

Validation Scenario

Scenario

Expected Result

How to Verify

Troubleshooting

Next Steps

Related Docs