Overview

A category override can change on a transaction that has already been enriched and published to your egress topic.

The transaction category update topic notifies you of these changes. Each message identifies a single transaction and the category override now applied to it, so you can keep your own records aligned without re-requesting enrichment or polling the API.

This topic carries category overrides only. Categories produced by the enrichment engine are delivered on your egress topic; see Egress message format.

Topic

This follows the same naming convention as the other Moneyhub-hosted topics; see Moneyhub-Hosted Apache Kafka. Where no topic name is configured for your environment, the default is customer-notifications-transactions-update. Moneyhub will confirm the name for your environment during onboarding.

Your Kafka principal requires read access to this topic in addition to your egress topic. See Kafka Authentication & Authorisation.

When notifications are sent

Notifications are published after either of the operations below. Only transactions whose category override actually changes are notified, so an operation that leaves a transaction unchanged produces no message for it.

Deleting a custom category

Deleting a custom category with Delete a custom category clears the override from every transaction that was assigned that category. Each of those transactions is notified, with user_category_id set to null.

Recategorising past and future transactions

Recategorising a transaction with Update an enriched transaction using recategorisationType=past-and-future also applies the override to the user's existing matching transactions. That work runs asynchronously after the API has responded, so notifications may arrive shortly after your request completes.

Each existing transaction that receives the override is notified. The transaction identified in the request itself is not notified on this topic, because its updated category is returned to you in the API response.

Message format

The Kafka message value is a JSON object. One message is published per changed transaction.

Example (override applied)

{
  "transaction_id": "50317ba9-957c-4001-b8b3-3c86ab4ada77",
  "user_category_id": "2779fa44-329e-4e04-ad5d-b931041d0634"
}

Example (override cleared)

{
  "transaction_id": "50317ba9-957c-4001-b8b3-3c86ab4ada77",
  "user_category_id": null
}

Delivery

Messages are delivered at least once. The same change may be published more than once, and a transaction is notified again each time its override subsequently changes.

Every message carries the complete override value for the transaction rather than an instruction to change it, so applying the same message twice has no additional effect. Deduplicate on transaction_id where you only need the current value for each transaction.

A single operation can affect many transactions, and each is published as its own message. Expect the messages for one operation to arrive over a short period rather than together.

Related

• Categories — how category overrides work and the recategorisation types available.
• Egress message format — categories produced during enrichment.
• Moneyhub-Hosted Apache Kafka — topic naming across all interfaces.