Skip to main content
Use the following reference for field-level detail when you work with Sync Hub events and files. For the concepts behind these contracts, see Integration patterns. For deployment and platform configuration, see Sync Hub deployment and configuration.

​
Event envelope

Every event published to Sync Hub uses a common envelope. The envelope fields travel as HTTP request headers on the publish request. The request body carries the event payload in a top-level data object. The producer validates that the request body contains a top-level data object. A request without data fails with an HTTP 422 status. The structure of data depends on the topic and event type. All other envelope fields are HTTP headers. For more information, see Request headers.

​
Publish endpoints

The Sync Hub producer exposes HTTP endpoints for publishing events. Pass the topic name as a path variable. The following table lists the publish endpoints on the producer service. The batch endpoint accepts a JSON array of event payloads in the request body. Batch requests require the eventSource, eventVersion, and traceParent headers. The identifier header doesn’t apply to batch publish. The producer accepts publish requests only from inside the runtime cluster. The service URL follows the Kubernetes FQDN pattern:
The default Helm release name is asb-producer, so the full endpoint for a topic looks like this:
Some runtimes deploy a versioned release name such as asb-producer-v0. Confirm the release name in the Application manifest for your runtime before you wire a connector.

​
Request headers

The producer reads the following HTTP headers on each publish request. The following table lists the required headers. The following table lists the optional headers.

​
Connector properties

An inbound connector doesn’t construct the publish HTTP call by hand. You wire the connector to the producer through the following properties, and the connector sets the matching headers on every publish. The following table describes the connector properties for publishing to Sync Hub. The connector builds the full endpoint as ${asb.producer.apiUri}/${asb.event.topic}/publish. Per-request values such as identifier and traceParent change for each event, so the connector sets them on the outbound request itself. For an example properties block, see Call the producer from an inbound connector.

​
Topics and subscriptions

You manage topics and subscriptions declaratively in the servicebus.values.yaml file under the synchub folder of your runtime in the gc-{installation}-applications-live repository. ArgoCD applies changes through Azure Service Operator. Key behaviors to be aware of:
  • Topic names are lowercase slugs, for example payment-status or party-updates.
  • The requiresSession value on a subscription (from the servicebus.values.yaml file) must match the sessionEnabled value in the consumer configuration for that subscription. A mismatch causes the processing client to fail.
  • maxDeliveryCount (from the subscription configuration) controls how many delivery attempts Azure Service Bus makes before it moves a message to the dead letter queue.
For the full configuration schema, see Configuration schema.

​
Delivery and failure behavior

Sync Hub combines Azure Service Bus behavior with consumer-side retry configuration. The following table describes the delivery and failure behavior. Messages in a dead letter queue don’t block subsequent events. Inspect dead letter queues through Azure Service Bus tooling. For more information, see Service Bus explorer.

​
File-processing conventions

Sync Hub doesn’t process files itself. File-based integrations follow this division of responsibility:
  • A connector picks up files from external storage, for example SFTP or Azure Blob Storage.
  • The connector parses and validates the file, then processes each record.
  • The connector publishes status and lifecycle events to Sync Hub topics so downstream systems stay synchronized.
  • Failed records follow the same retry and dead letter behavior as any other event.
For a working example of this pattern, see the OBPM batch connector. For the concepts behind file processing, see File processing.

​
Next steps