Building Producers

Goal

Publish platform events from your service into Integration Hub so that they are automatically distributed to all registered subscribers via HTTP webhooks.

Audience

Developers building services that produce events for downstream consumption through Integration Hub's subscription-based distribution system.

Prerequisites

• A running event bus cluster with access to Integration Hub's ingestion topics
• Protobuf tooling configured in your build pipeline
• Access to the event proto artifact from the internal artifact registry
• Basic understanding of event bus producer configuration

Before You Start

Integration Hub ingests events from event bus topics — not through a direct API call. Your service publishes events to a designated ingestion topic. Integration Hub consumes them, resolves matching subscriptions, and delivers events to all registered subscribers via HTTP webhooks.

note

The Integration Hub also accepts events via gRPC from Event Hub and REST endpoints. However, the primary ingestion path for platform services is through event bus topics.

Worked Example

In this guide, you publish a user lifecycle event from your service to the event bus ingestion topic. The Integration Hub picks it up, finds matching subscriptions, and distributes it to all registered subscribers.

Steps

1. Add the proto artifact dependency

Add the event proto artifact to your project. This artifact contains the event message definition and all sub-event types. Obtain the artifact coordinates and version from the internal artifact registry.

pom.xml

<dependency>
    <groupId>${event.proto.groupId}</groupId>
    <artifactId>${event.proto.artifactId}</artifactId>
    <version>${event.proto.version}</version>
</dependency>

warning

The artifact version must match the version used by the Integration Hub deployment. Mismatched versions may cause deserialization failures in the pipeline.

2. Configure the event bus producer

Configure your event bus producer to connect to the ingestion topic. The specific configuration depends on your application framework. The key settings are the ingestion topic name, the Protobuf serializer, and the acknowledgment mode.

application.properties (example)

# Event bus producer configuration
event-bus.producer.topic=${INGESTION_TOPIC_NAME}
event-bus.producer.value.serializer=<protobuf-serializer-class>
event-bus.producer.bootstrap.servers=${EVENT_BUS_BOOTSTRAP_SERVERS}
event-bus.producer.schema.registry.url=${SCHEMA_REGISTRY_URL}
event-bus.producer.acks=all

Property	Description
topic	The event bus topic the Integration Hub consumes from — obtain the topic name from your platform team
value.serializer	Protobuf serializer that registers the schema in Schema Registry
acks	all requires all in-sync replicas to persist the message before acknowledging

3. Build and publish the event message

Construct a Protobuf event message with all required fields and publish it to the event bus ingestion topic.

EventPublisher.java (simplified)

public class EventPublisher {

    private final EventBusProducer<String, EventMessage> producer;

    public void publishUserCreatedEvent(String userId, String sourceService) {
        EventMessage event = EventMessage.newBuilder()
            .setEventId(UUID.randomUUID().toString())
            .setEventType("user.lifecycle")
            .setSourceService(sourceService)
            .setCreatedAt(Timestamps.fromMillis(System.currentTimeMillis()))
            // Set the appropriate sub-event payload
            .build();

        ProducerRecord<String, EventMessage> record =
            new ProducerRecord<>(ingestionTopic, event.getEventId(), event);

        producer.send(record, (metadata, error) -> {
            if (error != null) {
                logger.error("Failed to publish event: {}", event.getEventId(), error);
            } else {
                logger.info("Event published: {}", event.getEventId());
            }
        });
    }
}

Key requirements for the event message:

Field	Requirement
eventId	Non-empty UUID string — used as the message key
eventType	Valid event type value matching the proto enum
sourceService	Non-empty string identifying your service
oneof event	Exactly one sub-event must be set, matching the eventType

4. Ensure matching subscriptions exist

For your events to reach subscribers, matching subscription event definitions must exist in the Subscription Management service. Use the REST API to register the event type if it does not exist yet.

Register event type via REST API

curl -X POST https://<SUBSCRIPTION_SERVICE_HOST>/api/v1/events \
  -H "Content-Type: application/json" \
  -d '{
    "event": {
      "id": "<EVENT_UUID>",
      "sourceService": "my-service",
      "eventType": "user.created",
      "resourceType": "user",
      "operationType": "CREATE"
    }
  }'

The Integration Hub uses these event definitions to resolve matching subscriptions. The lookup matches on sourceService, eventType, resourceType, and operationType.

5. Handle acknowledgment and errors

Monitor the event bus producer acknowledgment to handle send failures:

Error handling pattern

producer.send(record, (metadata, error) -> {
    if (error != null) {
        logger.error("Failed to publish event: {}", event.getEventId(), error);
        // Implement retry or fallback logic
    } else {
        logger.info("Event published to partition {} at offset {}",
            metadata.partition(), metadata.offset());
    }
});

tip

Use acks=all in your producer configuration. Integration Hub guarantees at-least-once delivery to all subscribers.

Validation Scenario

Scenario

Your service publishes a user creation event to the event bus ingestion topic, and a subscriber receives it via HTTP webhook.

Expected Result

1. The event appears on the ingestion event bus topic
2. The Integration Hub consumes it and resolves matching subscriptions
3. Integration Hub creates a delivery envelope for each matching subscriber
4. The Integration Hub delivers the event to each subscriber's webhook endpoint

How to Verify

• Event bus evidence: Check the ingestion topic for your published message using a consumer or management tool
• Logs: Integration Hub logs show subscription resolution for your event
• API evidence: Query the dead-letter topic API — if delivery failed, the event appears there with error details
• Audit evidence: Audit service receives audit logs for each processing stage

Troubleshooting

• Event not picked up by Integration Hub — Verify the topic name matches the configured ingestion topic exactly. Check the Integration Hub's consumer group offset.
• No subscriptions matched — Verify that a subscription event definition exists with matching sourceService, eventType, resourceType, and operationType values.
• Serialization failure — Ensure your Protobuf serializer version is compatible with the Schema Registry. Check that the schema is registered correctly.
• Schema Registry unreachable — The Protobuf serializer requires Schema Registry access. If unreachable, the send fails. Verify schema.registry.url in your configuration.

Next Steps

After building your producer, set up a subscriber to receive events: Building Consumers.

Related Docs

Integration Hub Overview

Architecture and end-to-end event flow.

Producer Model

How events are categorized and routed to domain topics.

Event-Driven Distribution

Domain topic routing and fan-out mechanism.

Event Hub Overview

Upstream event routing component.