> ## Documentation Index
> Fetch the complete documentation index at: https://agenticbanking.backbase.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Sync Hub events and files reference

> Reference for the Sync Hub event envelope, publish endpoints, headers, connector properties, delivery behavior, and file-processing conventions

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](/platform/sync-hub/integration-patterns). For deployment and platform configuration, see [Sync Hub deployment and configuration](/platform/sync-hub/deployment).

## 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](#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.

| Method | Path | Description |
| :- | :- | :- |
| <span className="http-method-post">POST</span> | `/{topic}/publish` | Publish a single event to the given topic. |
| <span className="http-method-post">POST</span> | `/{topic}/publish/batch` | Publish a batch of events to the given topic. |

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:

```text theme={"system"}
http://{RELEASE_NAME}.synchub-producer.svc.cluster.local
```

The default Helm release name is `asb-producer`, so the full endpoint for a topic looks like this:

```text theme={"system"}
http://asb-producer.synchub-producer.svc.cluster.local/payment-status/publish
```

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.

| Header | Description |
| :- | :- |
| `eventSource` | Source of the generated event |
| `eventVersion` | Version of the event schema |
| `identifier` | Unique identifier of the target resource |
| `traceParent` | Unique tracing ID |

The following table lists the optional headers.

| Header | Description |
| :- | :- |
| `bbEventType` | Backbase event spec class for the payload |
| `traceState` | Vendor-specific trace identification |
| `dateTime` | Timestamp of the event |

## 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.

| Property | Maps to | Description |
| :- | :- | :- |
| `asb.event.type` | `bbEventType` header | Backbase event spec class for the payload |
| `asb.event.source` | `eventSource` header | Source domain that produced the event |
| `asb.event.version` | `eventVersion` header | Schema version of the event |
| `asb.event.topic` | `{topic}` path variable | Azure Service Bus topic to publish to |
| `asb.producer.apiUri` | Endpoint base URL | Base URL of the producer service in the same runtime |

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](/platform/sync-hub/deployment#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](/platform/sync-hub/deployment#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.

| Behavior | Source | Detail |
| :- | :- | :- |
| Consumer retry | `backbase.grandcentral.retry.*` consumer properties | Defaults: `maxAttempts` 3, `delay` 2000 ms, `multiplier` 2 (exponential backoff) |
| Dead lettering on expiration | `deadLetteringOnMessageExpiration` subscription property | Expired messages move to the dead letter queue when set to `true` |
| Dead lettering after retries | `maxDeliveryCount` subscription property | Messages move to the dead letter queue after the configured number of delivery attempts |
| Message ordering | `sessionGroups.${topic}.sessionList` producer property | Session groups ensure ordering for messages that share a session |
| Concurrent processing | `topicConsumers.${topic}.${subscription}.numOfConcurrentSessions` consumer property | Sets how many sessions the consumer processes in parallel |

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](/platform/developer-guides/run#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](/connectors/payments/obpm-batch/get-started). For the concepts behind file processing, see [File processing](/platform/sync-hub/integration-patterns#3-file-processing).

## Next steps

* [Monitor and troubleshoot Sync Hub](/platform/sync-hub/monitoring): Dashboards, log queries, and common errors.
* [Sync Hub go-live checklist](/platform/sync-hub/go-live-checklist): Verify your Sync Hub setup before production.
* [Build a connector that publishes events](/platform/developer-guides/build/sync-hub-events): Apply this reference in a custom connector.