Gemba Finance AsyncAPI 0.1.0 documentation

Gemba Finance AsyncAPI 0.1.0

Event-driven APIs for the Gemba Finance platform. This specification documents all Kafka-based event streams and message channels used across Gemba services.

#notifications
#company-status
#cdc
#identity

Servers

kafka://bootstrap.testing-kafka-cluster.europe-west2.managedkafka.identity-dev-433210.cloud.goog:9092/kafkatesting
Testing environment Kafka cluster

object
environment
required
string
Environment name used in topic naming (e.g., testing-notifications)

Default value:"testing"
Security:
security.protocol:PLAINTEXT
object
schemaRegistryUrl
https://schema-registry.testing.gemba.dev
#environment
kafka://bootstrap.production-kafka-cluster.europe-west2.managedkafka.services-prod-437113.cloud.goog:9092/kafkaproduction
Production Kafka cluster

object
environment
required
string
Environment name used in topic naming (e.g., production-notifications)

Default value:"production"
Security:
security.protocol:PLAINTEXT
object
schemaRegistryUrl
https://schema-registry.production.gemba.dev
#environment

Operations

SEND ${{environment}}-notifications
Channel for notification commands to be processed by the notifications service. Messages are consumed by the notifications service and sent via Courier.

Topic format: {environment}-notifications Examples:

testing-notifications

production-notifications Partition key: userId (when available) to ensure ordered processing per user.
Publish notification command
Published when a service needs to send a notification (email, SMS, push)

Operation IDpublishNotification
Available only on servers:
- testing
- production
object
topic
${{environment}}-notifications
partitions
10
replicas
3
- #notifications
Accepts one of the following messages:
- #0Client Notification Command
  Command to send notification to a client
  application/json
  Message IDclientNotification
  object
  type
  required
  string
  Notification event type
  
  Allowed values:
  "CLIENT_NOTIFICATION"
  notificationId
  string
  format: uuid
  Optional unique notification identifier
  
  correlationId
  string
  Optional correlation ID for tracking
  
  required
  object
  required
  oneOf
  object
  userId
  required
  string
  format: uuid
  Target user ID
  
  clientId
  required
  string
  format: uuid
  Client ID
  
  array<string>
  Delivery channels
  
  Items:
  string
  Additional properties are allowed.
  object
  email
  required
  string
  format: email
  Client email address
  
  Additional properties are allowed.
  object
  sms
  required
  string
  Client SMS number
  
  Additional properties are allowed.
  template
  required
  string
  Notification template identifier
  
  Allowed values:
  "PROVIDE_AML_DOCUMENTS"
  "DORMANT_ACCOUNT_VERIFICATION"
  "OUTGOING_PAYMENT_SENT"
  oneOf
  object [PROVIDE_AML_DOCUMENTS Data]
  Data schema for PROVIDE_AML_DOCUMENTS template
  
  url
  required
  string
  format: uri
  URL for document submission
  
  transactionId
  required
  string
  Transaction identifier
  
  counterParty
  required
  string
  Counter party name
  
  clientName
  string
  Optional client name
  
  Additional properties are allowed.
  object [DORMANT_ACCOUNT_VERIFICATION Data]
  Data schema for DORMANT_ACCOUNT_VERIFICATION template
  
  url
  required
  string
  format: uri
  URL for account verification
  
  transactionId
  required
  string
  Transaction identifier
  
  clientName
  string
  Optional client name
  
  Additional properties are allowed.
  object [OUTGOING_PAYMENT_SENT Data]
  Data schema for OUTGOING_PAYMENT_SENT template
  
  clientName
  required
  string
  Client name
  
  amountWithCurrency
  required
  string
  Formatted amount with currency (e.g., "1,234.56 GBP")
  
  beneficiaryName
  required
  string
  Beneficiary name
  
  Additional properties are allowed.
  object oneOf
  White label configuration
  
  object
  domain
  required
  string
  White label domain
  
  Additional properties are allowed.
  object
  clientId
  required
  string
  format: uuid
  White label client ID
  
  Additional properties are allowed.
  Additional properties are allowed.
  Additional properties are allowed.
  Additional properties are allowed.
  #notifications
  Examples
  #1 Example - MacrobankOutgoingPaymentExample
  Example macrobank outgoing payment notification
  { "type": "CLIENT_NOTIFICATION", "payload": { "to": { "clientId": "bd73b0c9-5816-da4f-27e5-a9bd2736f41c", "userId": "4cdd598a-bc3f-64e7-1029-0bc4ef85a71d" }, "template": "OUTGOING_PAYMENT_SENT", "data": { "clientName": "John Doe", "amountWithCurrency": "1,234.56 GBP", "beneficiaryName": "ACME Corporation Ltd" } } }
- #1Applicant Notification Command
  Command to send notification to an applicant (pre-client)
  application/json
  Message IDapplicantNotification
  object
  type
  required
  string
  Notification event type
  
  Allowed values:
  "APPLICANT_NOTIFICATION"
  notificationId
  string
  format: uuid
  Optional unique notification identifier
  
  correlationId
  string
  Optional correlation ID for tracking
  
  required
  object
  required
  oneOf
  object
  email
  required
  string
  format: email
  Applicant email address
  
  Additional properties are allowed.
  object
  sms
  required
  string
  Applicant SMS number
  
  Additional properties are allowed.
  object
  email
  required
  string
  format: email
  Applicant email address
  
  sms
  required
  string
  Applicant SMS number
  
  Additional properties are allowed.
  template
  required
  string
  Notification template identifier
  
  Allowed values:
  "REMINDER_TO_COMPLETE_ONBOARDING"
  "REMINDER_TO_COMPLETE_PAYROLL"
  "CREATE_ACCOUNT"
  "EMAIL_PHONE_VERIFICATION"
  object
  Template-specific data
  
  Additional properties are allowed.
  object oneOf
  White label configuration
  
  object
  domain
  required
  string
  White label domain
  
  Additional properties are allowed.
  object
  clientId
  required
  string
  format: uuid
  White label client ID
  
  Additional properties are allowed.
  Additional properties are allowed.
  Additional properties are allowed.
  Additional properties are allowed.
  #notifications
  Examples
  { "type": "APPLICANT_NOTIFICATION", "notificationId": "2d591c23-85b1-4e8c-a6bd-74d89f8955c5", "correlationId": "string", "payload": { "to": { "email": "user@example.com" }, "template": "REMINDER_TO_COMPLETE_ONBOARDING", "data": {}, "whiteLabel": { "domain": "string" } } }
  
  This example has been generated automatically.
- #2Internal Notification Command
  Command to send internal notifications (admin, support, etc.)
  application/json
  Message IDinternalNotification
  object
  type
  required
  string
  Notification event type
  
  Allowed values:
  "INTERNAL_NOTIFICATION"
  notificationId
  string
  format: uuid
  Optional unique notification identifier
  
  correlationId
  string
  Optional correlation ID for tracking
  
  required
  object
  required
  oneOf
  object
  staffPerson
  required
  string
  format: email
  Staff member email address
  
  array<string>
  Delivery channels
  
  Items:
  string
  Allowed values:
  "email"
  "sms"
  "slack"
  Additional properties are allowed.
  object
  slackChannel
  required
  string
  Slack channel name
  
  Additional properties are allowed.
  template
  required
  string
  Notification template identifier
  
  Allowed values:
  "NEW_APPLICANT_IN_HOLD"
  object
  Template-specific data
  
  Additional properties are allowed.
  Additional properties are allowed.
  Additional properties are allowed.
  #notifications
  Examples
  { "type": "INTERNAL_NOTIFICATION", "notificationId": "2d591c23-85b1-4e8c-a6bd-74d89f8955c5", "correlationId": "string", "payload": { "to": { "staffPerson": "user@example.com", "channels": [ "email" ] }, "template": "NEW_APPLICANT_IN_HOLD", "data": {} } }
  
  This example has been generated automatically.
RECEIVE ${{environment}}-notifications
Channel for notification commands to be processed by the notifications service. Messages are consumed by the notifications service and sent via Courier.

Topic format: {environment}-notifications Examples:

testing-notifications

production-notifications Partition key: userId (when available) to ensure ordered processing per user.
Subscribe to notification commands
Consume notification commands for processing and delivery via Courier

Operation IDsubscribeNotificationCommands
Available only on servers:
- testing
- production
object
topic
${{environment}}-notifications
partitions
10
replicas
3
- #notifications
Accepts one of the following messages:
- #0Client Notification Command
  Command to send notification to a client
  application/json
  Message IDclientNotification
  object
  type
  required
  string
  Notification event type
  
  Allowed values:
  "CLIENT_NOTIFICATION"
  notificationId
  string
  format: uuid
  Optional unique notification identifier
  
  correlationId
  string
  Optional correlation ID for tracking
  
  required
  object
  required
  oneOf
  object
  userId
  required
  string
  format: uuid
  Target user ID
  
  clientId
  required
  string
  format: uuid
  Client ID
  
  array<string>
  Delivery channels
  
  Items:
  string
  Additional properties are allowed.
  object
  email
  required
  string
  format: email
  Client email address
  
  Additional properties are allowed.
  object
  sms
  required
  string
  Client SMS number
  
  Additional properties are allowed.
  template
  required
  string
  Notification template identifier
  
  Allowed values:
  "PROVIDE_AML_DOCUMENTS"
  "DORMANT_ACCOUNT_VERIFICATION"
  "OUTGOING_PAYMENT_SENT"
  oneOf
  object [PROVIDE_AML_DOCUMENTS Data]
  Data schema for PROVIDE_AML_DOCUMENTS template
  
  url
  required
  string
  format: uri
  URL for document submission
  
  transactionId
  required
  string
  Transaction identifier
  
  counterParty
  required
  string
  Counter party name
  
  clientName
  string
  Optional client name
  
  Additional properties are allowed.
  object [DORMANT_ACCOUNT_VERIFICATION Data]
  Data schema for DORMANT_ACCOUNT_VERIFICATION template
  
  url
  required
  string
  format: uri
  URL for account verification
  
  transactionId
  required
  string
  Transaction identifier
  
  clientName
  string
  Optional client name
  
  Additional properties are allowed.
  object [OUTGOING_PAYMENT_SENT Data]
  Data schema for OUTGOING_PAYMENT_SENT template
  
  clientName
  required
  string
  Client name
  
  amountWithCurrency
  required
  string
  Formatted amount with currency (e.g., "1,234.56 GBP")
  
  beneficiaryName
  required
  string
  Beneficiary name
  
  Additional properties are allowed.
  object oneOf
  White label configuration
  
  object
  domain
  required
  string
  White label domain
  
  Additional properties are allowed.
  object
  clientId
  required
  string
  format: uuid
  White label client ID
  
  Additional properties are allowed.
  Additional properties are allowed.
  Additional properties are allowed.
  Additional properties are allowed.
  #notifications
  Examples
  #1 Example - MacrobankOutgoingPaymentExample
  Example macrobank outgoing payment notification
  { "type": "CLIENT_NOTIFICATION", "payload": { "to": { "clientId": "bd73b0c9-5816-da4f-27e5-a9bd2736f41c", "userId": "4cdd598a-bc3f-64e7-1029-0bc4ef85a71d" }, "template": "OUTGOING_PAYMENT_SENT", "data": { "clientName": "John Doe", "amountWithCurrency": "1,234.56 GBP", "beneficiaryName": "ACME Corporation Ltd" } } }
- #1Applicant Notification Command
  Command to send notification to an applicant (pre-client)
  application/json
  Message IDapplicantNotification
  object
  type
  required
  string
  Notification event type
  
  Allowed values:
  "APPLICANT_NOTIFICATION"
  notificationId
  string
  format: uuid
  Optional unique notification identifier
  
  correlationId
  string
  Optional correlation ID for tracking
  
  required
  object
  required
  oneOf
  object
  email
  required
  string
  format: email
  Applicant email address
  
  Additional properties are allowed.
  object
  sms
  required
  string
  Applicant SMS number
  
  Additional properties are allowed.
  object
  email
  required
  string
  format: email
  Applicant email address
  
  sms
  required
  string
  Applicant SMS number
  
  Additional properties are allowed.
  template
  required
  string
  Notification template identifier
  
  Allowed values:
  "REMINDER_TO_COMPLETE_ONBOARDING"
  "REMINDER_TO_COMPLETE_PAYROLL"
  "CREATE_ACCOUNT"
  "EMAIL_PHONE_VERIFICATION"
  object
  Template-specific data
  
  Additional properties are allowed.
  object oneOf
  White label configuration
  
  object
  domain
  required
  string
  White label domain
  
  Additional properties are allowed.
  object
  clientId
  required
  string
  format: uuid
  White label client ID
  
  Additional properties are allowed.
  Additional properties are allowed.
  Additional properties are allowed.
  Additional properties are allowed.
  #notifications
  Examples
  { "type": "APPLICANT_NOTIFICATION", "notificationId": "2d591c23-85b1-4e8c-a6bd-74d89f8955c5", "correlationId": "string", "payload": { "to": { "email": "user@example.com" }, "template": "REMINDER_TO_COMPLETE_ONBOARDING", "data": {}, "whiteLabel": { "domain": "string" } } }
  
  This example has been generated automatically.
- #2Internal Notification Command
  Command to send internal notifications (admin, support, etc.)
  application/json
  Message IDinternalNotification
  object
  type
  required
  string
  Notification event type
  
  Allowed values:
  "INTERNAL_NOTIFICATION"
  notificationId
  string
  format: uuid
  Optional unique notification identifier
  
  correlationId
  string
  Optional correlation ID for tracking
  
  required
  object
  required
  oneOf
  object
  staffPerson
  required
  string
  format: email
  Staff member email address
  
  array<string>
  Delivery channels
  
  Items:
  string
  Allowed values:
  "email"
  "sms"
  "slack"
  Additional properties are allowed.
  object
  slackChannel
  required
  string
  Slack channel name
  
  Additional properties are allowed.
  template
  required
  string
  Notification template identifier
  
  Allowed values:
  "NEW_APPLICANT_IN_HOLD"
  object
  Template-specific data
  
  Additional properties are allowed.
  Additional properties are allowed.
  Additional properties are allowed.
  #notifications
  Examples
  { "type": "INTERNAL_NOTIFICATION", "notificationId": "2d591c23-85b1-4e8c-a6bd-74d89f8955c5", "correlationId": "string", "payload": { "to": { "staffPerson": "user@example.com", "channels": [ "email" ] }, "template": "NEW_APPLICANT_IN_HOLD", "data": {} } }
  
  This example has been generated automatically.
SEND ${{environment}}-company-status
Channel for company registry status update to be processed. Messages are published by job-company service when a company's status is updated in the official registry and requires action on Macrobank's site. Topic format: {environment}-company-status Examples:

testing-company-status

production-company-status
Update company status
Published when a company's registry status updated and requires action on Macrobanks's site (blocking, freezing).

Operation IDpublishCompanyStatus
Available only on servers:
- testing
- production
object
topic
${{environment}}-company-status
partitions
10
replicas
3
- #company-status
Accepts the following message:
Company Status Event
Event published when a company's registry status is updated and requires action
application/json
Message IDcompanyStatusMessage
object
clientId
required
string
format: uuid
Macrobank client ID

companyNumber
required
string
non-empty
Company registration number

country
required
string
Company registry country code

Allowed values:
"GBR"
"IMN"
action
required
string
Required action based on company status:

fully_frozen: GBR company in liquidation (complete account freeze)

blocked_on_debit: GBR company in administration (block debit transactions)

block: IMN company dissolved or other blocking status

Allowed values:
"fully_frozen"
"blocked_on_debit"
"block"
registryStatus
required
string
non-empty
Company status from registry (e.g., "liquidation", "administration", "dissolved")

registryStatusDetail
required
string
Additional status detail from registry (e.g., "active-proposal-to-strike-off")

applicantId
string
Associated applicant ID if available

companyName
string
Company name from registry

timestamp
required
string
format: date-time
Event timestamp (ISO 8601)

correlationId
string
Optional correlation ID for tracking

source
required
string
Source service that published this event

Allowed values:
"job-company"
Additional properties are allowed.
#company-status
Examples
#1 Example - GBR Company in Liquidation
GBR company in liquidation requiring full freeze
{ "clientId": "bd73b0c9-5816-da4f-27e5-a9bd2736f41c", "companyNumber": "12345678", "country": "GBR", "action": "fully_frozen", "registryStatus": "liquidation", "registryStatusDetail": "voluntary-liquidation", "companyName": "Example Ltd", "timestamp": "2025-11-24T14:30:00Z", "source": "job-company" }

#2 Example - GBR Company in Administration
GBR company in administration requiring debit blocking
{ "clientId": "4cdd598a-bc3f-64e7-1029-0bc4ef85a71d", "companyNumber": "87654321", "country": "GBR", "action": "blocked_on_debit", "registryStatus": "administration", "registryStatusDetail": "voluntary-arrangement", "companyName": "Another Company Ltd", "applicantId": "550e8400-e29b-41d4-a716-446655440000", "timestamp": "2025-11-24T14:35:00Z", "correlationId": "trace-123-abc", "source": "job-company" }

#3 Example - IMN Company Dissolved
IMN company dissolved requiring blocking
{ "clientId": "7f8d9e0a-1b2c-3d4e-5f6g-7h8i9j0k1l2m", "companyNumber": "123456C", "country": "IMN", "action": "block", "registryStatus": "dissolved", "companyName": "Isle of Man Company Ltd", "timestamp": "2025-11-24T14:40:00Z", "source": "job-company" }
RECEIVE ${{environment}}-company-status
Channel for company registry status update to be processed. Messages are published by job-company service when a company's status is updated in the official registry and requires action on Macrobank's site. Topic format: {environment}-company-status Examples:

testing-company-status

production-company-status
Subscribe to company status events
Consume company status updates to process blocking actions on Macrobank's site.

Operation IDsubscribeCompanyStatus
Available only on servers:
- testing
- production
object
topic
${{environment}}-company-status
partitions
10
replicas
3
- #company-status
Accepts the following message:
Company Status Event
Event published when a company's registry status is updated and requires action
application/json
Message IDcompanyStatusMessage
object
clientId
required
string
format: uuid
Macrobank client ID

companyNumber
required
string
non-empty
Company registration number

country
required
string
Company registry country code

Allowed values:
"GBR"
"IMN"
action
required
string
Required action based on company status:

fully_frozen: GBR company in liquidation (complete account freeze)

blocked_on_debit: GBR company in administration (block debit transactions)

block: IMN company dissolved or other blocking status

Allowed values:
"fully_frozen"
"blocked_on_debit"
"block"
registryStatus
required
string
non-empty
Company status from registry (e.g., "liquidation", "administration", "dissolved")

registryStatusDetail
required
string
Additional status detail from registry (e.g., "active-proposal-to-strike-off")

applicantId
string
Associated applicant ID if available

companyName
string
Company name from registry

timestamp
required
string
format: date-time
Event timestamp (ISO 8601)

correlationId
string
Optional correlation ID for tracking

source
required
string
Source service that published this event

Allowed values:
"job-company"
Additional properties are allowed.
#company-status
Examples
#1 Example - GBR Company in Liquidation
GBR company in liquidation requiring full freeze
{ "clientId": "bd73b0c9-5816-da4f-27e5-a9bd2736f41c", "companyNumber": "12345678", "country": "GBR", "action": "fully_frozen", "registryStatus": "liquidation", "registryStatusDetail": "voluntary-liquidation", "companyName": "Example Ltd", "timestamp": "2025-11-24T14:30:00Z", "source": "job-company" }

#2 Example - GBR Company in Administration
GBR company in administration requiring debit blocking
{ "clientId": "4cdd598a-bc3f-64e7-1029-0bc4ef85a71d", "companyNumber": "87654321", "country": "GBR", "action": "blocked_on_debit", "registryStatus": "administration", "registryStatusDetail": "voluntary-arrangement", "companyName": "Another Company Ltd", "applicantId": "550e8400-e29b-41d4-a716-446655440000", "timestamp": "2025-11-24T14:35:00Z", "correlationId": "trace-123-abc", "source": "job-company" }

#3 Example - IMN Company Dissolved
IMN company dissolved requiring blocking
{ "clientId": "7f8d9e0a-1b2c-3d4e-5f6g-7h8i9j0k1l2m", "companyNumber": "123456C", "country": "IMN", "action": "block", "registryStatus": "dissolved", "companyName": "Isle of Man Company Ltd", "timestamp": "2025-11-24T14:40:00Z", "source": "job-company" }
SEND ${{environment}}-cdc-events
Channel for Change Data Capture (CDC) events from the Macrobank database.

The CDC service monitors SQL Server change tracking tables and publishes events when transfer statuses change. Events are published for:

Internal transfers (between Gemba accounts)

International transfers (SWIFT/SEPA)

UK transfers (Faster Payments/BACS/CHAPS)

Messages contain Base64-encoded JSON payloads with routing metadata in Kafka headers.

Topic format: {environment}-cdc-events Examples:

testing-cdc-events

production-cdc-events
Publish CDC transfer event
Published by the CDC service when a transfer status changes in the Macrobank database.

The CDC service monitors SQL Server change tracking tables for the following document classes:

IncomingPayment

Outgoing_Payment_FReq (International transfers)

Outgoing_SEPAPAY_FReq (SEPA payments)

Outgoing_British_FReq (UK transfers)

EP_TRANSFER (Internal transfers)

When a document's status changes to an API-visible state, the CDC service:

Retrieves the full transfer payload from the database

Base64-encodes the JSON payload

Publishes to Kafka with routing headers (clientId, accountId, type)

For internal transfers, two events are published:

transfer.outgoing.changed to the sender

transfer.incoming.created to the recipient
Operation IDpublishCDCEvent
Available only on servers:
- testing
- production
object
topic
${{environment}}-cdc-events
partitions
10
replicas
3
- #cdc
Accepts the following message:
CDC Event Message
Change Data Capture event published when transfer statuses change in Macrobank
application/json
Message IDcdcEventMessage
CDC events are published when transfer statuses change in the Macrobank database. The CDC service monitors SQL Server change tracking tables and publishes events to Kafka for downstream consumers.

Message Structure

The message consists of:

Value: Base64-encoded JSON payload containing the transfer details

Headers: Kafka headers with routing metadata (clientId, accountId, type)

Event Types

The type header indicates the event type:

transfer.outgoing.changed - Outgoing transfer status changed (sender perspective)

transfer.incoming.created - Incoming transfer created (recipient perspective, internal transfers only)

Payload Types

The Base64-decoded payload contains one of:

InternalTransfer - For transfers between Gemba accounts

InternationalTransfer - For SWIFT/SEPA transfers

UKTransfer - For UK Faster Payments/BACS/CHAPS transfers

Processing

Consumers should:

Read the type header to determine event type

Base64-decode the message value

Parse the JSON payload according to the transfer type

Use clientId and accountId headers for routing/filtering

Payload
string
format: byte
Base64-encoded JSON payload containing the transfer details.

When decoded, the payload is a JSON object matching one of:

InternalTransfer schema (for internal transfers)

InternationalTransfer schema (for international transfers)

UKTransfer schema (for UK transfers)

The specific schema depends on the source document class in the CDC change.

object
clientId
required
string
format: uuid
The Gemba client ID (GUID) for routing the event

accountId
required
string
format: uuid
The Gemba account ID (GUID) associated with the transfer

type
required
string
Event type indicating the nature of the change:

transfer.outgoing.changed: Outgoing transfer status changed

transfer.incoming.created: Incoming transfer created (internal transfers only)

Allowed values:
"transfer.outgoing.changed"
"transfer.incoming.created"
Additional properties are allowed.
object
key
string
Kafka message key for partitioning. Typically the eventType value or a GUID if eventType is not set.

#cdc
Examples
#1 Example - Internal Transfer - Outgoing Changed
Status change for an outgoing internal transfer
eyJpZCI6IjEyM2U0NTY3LWU4OWItMTJkMy1hNDU2LTQyNjYxNDE3NDAwMCIsInN0YXR1cyI6ImRvbmUiLCJhY2NvdW50SWQiOiIyMzRlNTY3OC1lODliLTEyZDMtYTQ1Ni00MjY2MTQxNzQwMDAiLCJhbW91bnQiOjEwMDAwMCwiZmVlIjo1MDAsInRvdGFsIjoxMDA1MDAsImN1cnJlbmN5Q29kZSI6IkVVUiIsImRlc2NyaXB0aW9uIjoiTW9udGhseSByZW50IHBheW1lbnQiLCJyZWNpcGllbnROYW1lIjoiSm9obiBEb2UiLCJyZWNpcGllbnRBY2NvdW50TnVtYmVyIjoiREU4OTM3MDQwMDQ0MDUzMjAxMzAwMCIsImNyZWF0ZWRBdCI6IjIwMjQtMDktMTZUMTQ6MzI6MDBaIn0=

#2 Example - Internal Transfer - Incoming Created
New incoming internal transfer for recipient
eyJpZCI6IjEyM2U0NTY3LWU4OWItMTJkMy1hNDU2LTQyNjYxNDE3NDAwMCIsInN0YXR1cyI6ImRvbmUiLCJhY2NvdW50SWQiOiIzNDVmNjc4OS1lODliLTEyZDMtYTQ1Ni00MjY2MTQxNzQwMDAiLCJhbW91bnQiOjEwMDAwMCwiZmVlIjo1MDAsInRvdGFsIjoxMDA1MDAsImN1cnJlbmN5Q29kZSI6IkVVUiIsImRlc2NyaXB0aW9uIjoiTW9udGhseSByZW50IHBheW1lbnQiLCJyZWNpcGllbnROYW1lIjoiSm9obiBEb2UiLCJyZWNpcGllbnRBY2NvdW50TnVtYmVyIjoiREU4OTM3MDQwMDQ0MDUzMjAxMzAwMCIsImNyZWF0ZWRBdCI6IjIwMjQtMDktMTZUMTQ6MzI6MDBaIn0=

#3 Example - International Transfer - Outgoing Changed
Status change for an outgoing international transfer
eyJpZCI6IjQ1NmE3ODkwLWU4OWItMTJkMy1hNDU2LTQyNjYxNDE3NDAwMCIsInN0YXR1cyI6Imlucm9ncmVzcyIsImFjY291bnRJZCI6IjQ1NmE3ODkwLWU4OWItMTJkMy1hNDU2LTQyNjYxNDE3NDAwMCIsImFtb3VudCI6NTAwMDAwLCJmZWUiOjI1MDAsInRvdGFsIjo1MDI1MDAsImN1cnJlbmN5Q29kZSI6IlVTRCIsImRlc2NyaXB0aW9uIjoiSW52b2ljZSBwYXltZW50IiwicmVjaXBpZW50TmFtZSI6IkFjbWUgQ29ycCIsInJlY2lwaWVudEFjY291bnROdW1iZXIiOiJVUzEyMzQ1Njc4OTAiLCJyZWNpcGllbnRBY2NvdW50VHlwZSI6ImNvbXBhbnkiLCJyZWNpcGllbnRBZGRyZXNzIjoiMTIzIE1haW4gU3QsIE5ldyBZb3JrIiwicmVjaXBpZW50Q291bnRyeSI6IlVTIiwicmVjaXBpZW50UmVnaXN0cmF0aW9uTnVtYmVyIjoiVVMxMjM0NTY3ODkiLCJjaGFyZ2VzVHlwZSI6InNoYXJlZCIsImJhbmtOYW1lIjoiQmFuayBvZiBBbWVyaWNhIiwiYmFua0FkZHJlc3MiOiIxMDAgTiBUcnlvbiBTdCIsImJhbmtDb3VudHJ5IjoiVVMiLCJiYW5rQklDIjoiQk9GQVVTMk4iLCJjcmVhdGVkQXQiOiIyMDI0LTA5LTE2VDE0OjMyOjAwWiJ9

#4 Example - UK Transfer - Outgoing Changed
Status change for an outgoing UK transfer
eyJpZCI6IjU2N2I4OTAxLWU4OWItMTJkMy1hNDU2LTQyNjYxNDE3NDAwMCIsInN0YXR1cyI6ImRvbmUiLCJhY2NvdW50SWQiOiI1NjdiODkwMS1lODliLTEyZDMtYTQ1Ni00MjY2MTQxNzQwMDAiLCJhbW91bnQiOjEwMDAwMCwiZmVlIjo1MCwidG90YWwiOjEwMDA1MCwiY3VycmVuY3lDb2RlIjoiR0JQIiwiZGVzY3JpcHRpb24iOiJNb250aGx5IHJlbnQiLCJyZWNpcGllbnROYW1lIjoiSmFuZSBTbWl0aCIsInJlY2lwaWVudEFjY291bnROdW1iZXIiOiIxMjM0NTY3OCIsInJlY2lwaWVudEFjY291bnRUeXBlIjoiaW5kaXZpZHVhbCIsInR5cGUiOiJmYXN0ZXJfcGF5bWVudHMiLCJzb3J0Q29kZSI6IjEyMzQ1NiIsImJhbmtOYW1lIjoiQmFyY2xheXMgQmFuayIsImJhbmtBZGRyZXNzIjoiMSBDaHVyY2hpbGwgUGxhY2UsIExvbmRvbiIsImNyZWF0ZWRBdCI6IjIwMjQtMDktMTZUMTQ6MzI6MDBaIn0=

#1 Example - Internal Transfer - Outgoing Changed
Status change for an outgoing internal transfer
{ "clientId": "bd73b0c9-5816-da4f-27e5-a9bd2736f41c", "accountId": "234e5678-e89b-12d3-a456-426614174000", "type": "transfer.outgoing.changed" }

#2 Example - Internal Transfer - Incoming Created
New incoming internal transfer for recipient
{ "clientId": "4cdd598a-bc3f-64e7-1029-0bc4ef85a71d", "accountId": "345f6789-e89b-12d3-a456-426614174000", "type": "transfer.incoming.created" }

#3 Example - International Transfer - Outgoing Changed
Status change for an outgoing international transfer
{ "clientId": "7f8d9e0a-1b2c-3d4e-5f6a-7b8c9d0e1f2a", "accountId": "456a7890-e89b-12d3-a456-426614174000", "type": "transfer.outgoing.changed" }

#4 Example - UK Transfer - Outgoing Changed
Status change for an outgoing UK transfer
{ "clientId": "8a9b0c1d-2e3f-4a5b-6c7d-8e9f0a1b2c3d", "accountId": "567b8901-e89b-12d3-a456-426614174000", "type": "transfer.outgoing.changed" }
RECEIVE ${{environment}}-cdc-events
Channel for Change Data Capture (CDC) events from the Macrobank database.

The CDC service monitors SQL Server change tracking tables and publishes events when transfer statuses change. Events are published for:

Internal transfers (between Gemba accounts)

International transfers (SWIFT/SEPA)

UK transfers (Faster Payments/BACS/CHAPS)

Messages contain Base64-encoded JSON payloads with routing metadata in Kafka headers.

Topic format: {environment}-cdc-events Examples:

testing-cdc-events

production-cdc-events
Subscribe to CDC transfer events
Consume CDC events to react to transfer status changes.

Use Cases

Mobile/Web Push Notifications: Send real-time notifications to users when their transfers complete

Webhook Delivery: Trigger webhook callbacks to client systems

Analytics/Reporting: Track transfer metrics and generate reports

Audit Logging: Maintain audit trail of transfer status changes

Processing Guidelines

Idempotency: Events may be delivered more than once. Use the transfer id for deduplication.

Ordering: Events for the same type are ordered within a partition. Different event types may arrive out of order.

Filtering: Use Kafka headers to filter events by clientId, accountId, or type.

Schema Handling: The payload type varies based on the source transfer. Handle InternalTransfer, InternationalTransfer, and UKTransfer schemas.
Operation IDsubscribeCDCEvent
Available only on servers:
- testing
- production
object
topic
${{environment}}-cdc-events
partitions
10
replicas
3
- #cdc
Accepts the following message:
CDC Event Message
Change Data Capture event published when transfer statuses change in Macrobank
application/json
Message IDcdcEventMessage
CDC events are published when transfer statuses change in the Macrobank database. The CDC service monitors SQL Server change tracking tables and publishes events to Kafka for downstream consumers.

Message Structure

The message consists of:

Value: Base64-encoded JSON payload containing the transfer details

Headers: Kafka headers with routing metadata (clientId, accountId, type)

Event Types

The type header indicates the event type:

transfer.outgoing.changed - Outgoing transfer status changed (sender perspective)

transfer.incoming.created - Incoming transfer created (recipient perspective, internal transfers only)

Payload Types

The Base64-decoded payload contains one of:

InternalTransfer - For transfers between Gemba accounts

InternationalTransfer - For SWIFT/SEPA transfers

UKTransfer - For UK Faster Payments/BACS/CHAPS transfers

Processing

Consumers should:

Read the type header to determine event type

Base64-decode the message value

Parse the JSON payload according to the transfer type

Use clientId and accountId headers for routing/filtering

Payload
string
format: byte
Base64-encoded JSON payload containing the transfer details.

When decoded, the payload is a JSON object matching one of:

InternalTransfer schema (for internal transfers)

InternationalTransfer schema (for international transfers)

UKTransfer schema (for UK transfers)

The specific schema depends on the source document class in the CDC change.

object
clientId
required
string
format: uuid
The Gemba client ID (GUID) for routing the event

accountId
required
string
format: uuid
The Gemba account ID (GUID) associated with the transfer

type
required
string
Event type indicating the nature of the change:

transfer.outgoing.changed: Outgoing transfer status changed

transfer.incoming.created: Incoming transfer created (internal transfers only)

Allowed values:
"transfer.outgoing.changed"
"transfer.incoming.created"
Additional properties are allowed.
object
key
string
Kafka message key for partitioning. Typically the eventType value or a GUID if eventType is not set.

#cdc
Examples
#1 Example - Internal Transfer - Outgoing Changed
Status change for an outgoing internal transfer
eyJpZCI6IjEyM2U0NTY3LWU4OWItMTJkMy1hNDU2LTQyNjYxNDE3NDAwMCIsInN0YXR1cyI6ImRvbmUiLCJhY2NvdW50SWQiOiIyMzRlNTY3OC1lODliLTEyZDMtYTQ1Ni00MjY2MTQxNzQwMDAiLCJhbW91bnQiOjEwMDAwMCwiZmVlIjo1MDAsInRvdGFsIjoxMDA1MDAsImN1cnJlbmN5Q29kZSI6IkVVUiIsImRlc2NyaXB0aW9uIjoiTW9udGhseSByZW50IHBheW1lbnQiLCJyZWNpcGllbnROYW1lIjoiSm9obiBEb2UiLCJyZWNpcGllbnRBY2NvdW50TnVtYmVyIjoiREU4OTM3MDQwMDQ0MDUzMjAxMzAwMCIsImNyZWF0ZWRBdCI6IjIwMjQtMDktMTZUMTQ6MzI6MDBaIn0=

#2 Example - Internal Transfer - Incoming Created
New incoming internal transfer for recipient
eyJpZCI6IjEyM2U0NTY3LWU4OWItMTJkMy1hNDU2LTQyNjYxNDE3NDAwMCIsInN0YXR1cyI6ImRvbmUiLCJhY2NvdW50SWQiOiIzNDVmNjc4OS1lODliLTEyZDMtYTQ1Ni00MjY2MTQxNzQwMDAiLCJhbW91bnQiOjEwMDAwMCwiZmVlIjo1MDAsInRvdGFsIjoxMDA1MDAsImN1cnJlbmN5Q29kZSI6IkVVUiIsImRlc2NyaXB0aW9uIjoiTW9udGhseSByZW50IHBheW1lbnQiLCJyZWNpcGllbnROYW1lIjoiSm9obiBEb2UiLCJyZWNpcGllbnRBY2NvdW50TnVtYmVyIjoiREU4OTM3MDQwMDQ0MDUzMjAxMzAwMCIsImNyZWF0ZWRBdCI6IjIwMjQtMDktMTZUMTQ6MzI6MDBaIn0=

#3 Example - International Transfer - Outgoing Changed
Status change for an outgoing international transfer
eyJpZCI6IjQ1NmE3ODkwLWU4OWItMTJkMy1hNDU2LTQyNjYxNDE3NDAwMCIsInN0YXR1cyI6Imlucm9ncmVzcyIsImFjY291bnRJZCI6IjQ1NmE3ODkwLWU4OWItMTJkMy1hNDU2LTQyNjYxNDE3NDAwMCIsImFtb3VudCI6NTAwMDAwLCJmZWUiOjI1MDAsInRvdGFsIjo1MDI1MDAsImN1cnJlbmN5Q29kZSI6IlVTRCIsImRlc2NyaXB0aW9uIjoiSW52b2ljZSBwYXltZW50IiwicmVjaXBpZW50TmFtZSI6IkFjbWUgQ29ycCIsInJlY2lwaWVudEFjY291bnROdW1iZXIiOiJVUzEyMzQ1Njc4OTAiLCJyZWNpcGllbnRBY2NvdW50VHlwZSI6ImNvbXBhbnkiLCJyZWNpcGllbnRBZGRyZXNzIjoiMTIzIE1haW4gU3QsIE5ldyBZb3JrIiwicmVjaXBpZW50Q291bnRyeSI6IlVTIiwicmVjaXBpZW50UmVnaXN0cmF0aW9uTnVtYmVyIjoiVVMxMjM0NTY3ODkiLCJjaGFyZ2VzVHlwZSI6InNoYXJlZCIsImJhbmtOYW1lIjoiQmFuayBvZiBBbWVyaWNhIiwiYmFua0FkZHJlc3MiOiIxMDAgTiBUcnlvbiBTdCIsImJhbmtDb3VudHJ5IjoiVVMiLCJiYW5rQklDIjoiQk9GQVVTMk4iLCJjcmVhdGVkQXQiOiIyMDI0LTA5LTE2VDE0OjMyOjAwWiJ9

#4 Example - UK Transfer - Outgoing Changed
Status change for an outgoing UK transfer
eyJpZCI6IjU2N2I4OTAxLWU4OWItMTJkMy1hNDU2LTQyNjYxNDE3NDAwMCIsInN0YXR1cyI6ImRvbmUiLCJhY2NvdW50SWQiOiI1NjdiODkwMS1lODliLTEyZDMtYTQ1Ni00MjY2MTQxNzQwMDAiLCJhbW91bnQiOjEwMDAwMCwiZmVlIjo1MCwidG90YWwiOjEwMDA1MCwiY3VycmVuY3lDb2RlIjoiR0JQIiwiZGVzY3JpcHRpb24iOiJNb250aGx5IHJlbnQiLCJyZWNpcGllbnROYW1lIjoiSmFuZSBTbWl0aCIsInJlY2lwaWVudEFjY291bnROdW1iZXIiOiIxMjM0NTY3OCIsInJlY2lwaWVudEFjY291bnRUeXBlIjoiaW5kaXZpZHVhbCIsInR5cGUiOiJmYXN0ZXJfcGF5bWVudHMiLCJzb3J0Q29kZSI6IjEyMzQ1NiIsImJhbmtOYW1lIjoiQmFyY2xheXMgQmFuayIsImJhbmtBZGRyZXNzIjoiMSBDaHVyY2hpbGwgUGxhY2UsIExvbmRvbiIsImNyZWF0ZWRBdCI6IjIwMjQtMDktMTZUMTQ6MzI6MDBaIn0=

#1 Example - Internal Transfer - Outgoing Changed
Status change for an outgoing internal transfer
{ "clientId": "bd73b0c9-5816-da4f-27e5-a9bd2736f41c", "accountId": "234e5678-e89b-12d3-a456-426614174000", "type": "transfer.outgoing.changed" }

#2 Example - Internal Transfer - Incoming Created
New incoming internal transfer for recipient
{ "clientId": "4cdd598a-bc3f-64e7-1029-0bc4ef85a71d", "accountId": "345f6789-e89b-12d3-a456-426614174000", "type": "transfer.incoming.created" }

#3 Example - International Transfer - Outgoing Changed
Status change for an outgoing international transfer
{ "clientId": "7f8d9e0a-1b2c-3d4e-5f6a-7b8c9d0e1f2a", "accountId": "456a7890-e89b-12d3-a456-426614174000", "type": "transfer.outgoing.changed" }

#4 Example - UK Transfer - Outgoing Changed
Status change for an outgoing UK transfer
{ "clientId": "8a9b0c1d-2e3f-4a5b-6c7d-8e9f0a1b2c3d", "accountId": "567b8901-e89b-12d3-a456-426614174000", "type": "transfer.outgoing.changed" }
SEND ${{environment}}-identity-commands
Channel for user identity events published by the Identity Service.

The Identity Service publishes user events after processing WorkOS webhooks. These events are consumed by Macrobank to create/update remote_user records.

Events include the gemba_services_user_id as the external ID for Macrobank.

Topic format: {environment}-identity-commands Examples:

identity-commands (development)

testing-identity-commands

production-identity-commands

Event Ordering: All user-related events (user.created, user.updated, user.deleted, user.suspended) are published to a single topic to maintain ordering guarantees. Events are partitioned by gemba_services_user_id to ensure all events for the same user are processed in order.

Partition key: gemba_services_user_id to ensure ordered processing per user.
Publish user.created event
Published by Identity Service when a WorkOS user is created. The event is triggered by a WorkOS webhook and includes the generated gemba_services_user_id for Macrobank consumption.

Operation IDpublishUserCreated
Available only on servers:
- testing
- production
object
topic
${{environment}}-identity-commands
partitions
10
replicas
3
- #identity
Accepts the following message:
User Created Event
Event published when a new user is created in WorkOS
application/json
Message IDuserCreated
Published by the Identity Service when a WorkOS user is created.

This event is triggered by a WorkOS user.created webhook. The Identity Service:

Generates a unique gemba_services_user_id (UUID)

Stores the mapping in the database

Enriches user profile data

Publishes this event to Kafka

Macrobank consumes this event to create the corresponding remote_user record using gemba_services_user_id as the external_id.

Profile Data Mapping

When creating the remote_user record, Macrobank should map the following fields:

email → remote_user.email (or remote_user.CliLogin if email not available)

first_name → DocDataRemoteAccount.Name (maps to remote_user.FirstName)

last_name → DocDataRemoteAccount.Surname (maps to remote_user.LastName)

Matching WorkOS User to Macrobank Client

The macrobank_client_id field in the event payload contains the Macrobank client UUID. This is the recommended way to determine which Macrobank client the user belongs to.

Alternative methods (if macrobank_client_id is not available):

Via WorkOS Organization:

Use workos_org_id from the event

Query WorkOS organization API to get the macrobank-client-id custom attribute

This gives you the Macrobank client UUID

Via Macrobank remote_user (After Creation):

After creating remote_user with external_id = gemba_services_user_id

Query Macrobank remote_users table by external_id

Get remote_user.client_id (INT) which links to Macrobank clients table

Note: The Identity Service looks up macrobank_client_id from the organization_mappings table using workos_org_id. This mapping is established when Identity Service provisions WorkOS organizations from Macrobank client.created events.

object
source
required
string
Source service identifier

Allowed values:
"identity-service"
event_type
required
string
Event type identifier

Allowed values:
"user.created"
gemba_services_user_id
required
string
format: uuid
Unique gemba-services user ID (UUID) generated by Identity Service. This is used as the external_id in Macrobank remote_users table.

workos_user_id
required
string
WorkOS user ID (from WorkOS webhook)

workos_org_id
string
WorkOS organization ID (optional)

macrobank_client_id
string
format: uuid
Macrobank client UUID (optional).

Usage: This is the recommended way to determine which Macrobank client the user belongs to. The Identity Service looks this up from the organization_mappings table using workos_org_id.

If not provided, use workos_org_id to query WorkOS organization API for the macrobank-client-id custom attribute.

object
Enriched user profile data (JSON object). Contains email, first_name, last_name, and other metadata.

Field Mappings to Macrobank:

email → remote_user.email (or remote_user.CliLogin if email not available)

first_name → DocDataRemoteAccount.Name (maps to remote_user.FirstName)

last_name → DocDataRemoteAccount.Surname (maps to remote_user.LastName)

email
string
format: email
User email address (maps to Macrobank remote_user.email)

first_name
string
User first name (maps to Macrobank DocDataRemoteAccount.Name)

last_name
string
User last name (maps to Macrobank DocDataRemoteAccount.Surname)

Additional properties are allowed.
timestamp
required
string
format: date-time
ISO 8601 timestamp when the event was published

Additional properties are allowed.
object
key
string
Kafka message key for partitioning. Uses gemba_services_user_id to ensure ordered processing per user.

#identity
Examples
#1 Example - User Created Example
Example user.created event
{ "source": "identity-service", "event_type": "user.created", "gemba_services_user_id": "550e8400-e29b-41d4-a716-446655440000", "workos_user_id": "user_01HZJXKQ8N7X9Y2Z3A4B5C6D7", "workos_org_id": "org_01HZJXKQ8N7X9Y2Z3A4B5C6D7", "macrobank_client_id": "bd73b0c9-5816-da4f-27e5-a9bd2736f41c", "profile_data": { "email": "user@example.com", "first_name": "John", "last_name": "Doe", "created_via": "workos_webhook" }, "timestamp": "2024-01-15T10:30:00Z" }
SEND ${{environment}}-identity-commands
Channel for user identity events published by the Identity Service.

The Identity Service publishes user events after processing WorkOS webhooks. These events are consumed by Macrobank to create/update remote_user records.

Events include the gemba_services_user_id as the external ID for Macrobank.

Topic format: {environment}-identity-commands Examples:

identity-commands (development)

testing-identity-commands

production-identity-commands

Event Ordering: All user-related events (user.created, user.updated, user.deleted, user.suspended) are published to a single topic to maintain ordering guarantees. Events are partitioned by gemba_services_user_id to ensure all events for the same user are processed in order.

Partition key: gemba_services_user_id to ensure ordered processing per user.
Publish user.updated event
Published by Identity Service when a WorkOS user is updated. The event is triggered by a WorkOS webhook and includes updated profile data for Macrobank consumption.

Operation IDpublishUserUpdated
Available only on servers:
- testing
- production
object
topic
${{environment}}-identity-commands
partitions
10
replicas
3
- #identity
Accepts the following message:
User Updated Event
Event published when a user is updated in WorkOS
application/json
Message IDuserUpdated
Published by the Identity Service when a WorkOS user is updated.

This event is triggered by a WorkOS user.updated webhook. The Identity Service:

Retrieves the existing gemba_services_user_id mapping

Updates the profile data

Publishes this event to Kafka

Macrobank consumes this event to update the corresponding remote_user record.

Profile Data Updates

Users can update their profile information in WorkOS, including:

email - Email address

first_name - First name

last_name - Last name

Other metadata fields

When Macrobank receives a user.updated event:

Email Updates:

Update remote_user.email (or remote_user.CliLogin if email is not available)

Name Updates:

Update DocDataRemoteAccount.Name with first_name (maps to remote_user.FirstName)

Update DocDataRemoteAccount.Surname with last_name (maps to remote_user.LastName)

Compliance Considerations:

WorkOS is the source of truth for user identities, so Macrobank should update the fields

Name changes may require compliance/KYC review depending on regulatory requirements

Macrobank may need to flag significant name changes for manual review

Consider triggering re-verification workflows for substantial name changes (e.g., complete name replacement)

Matching WorkOS User to Macrobank Client

The macrobank_client_id field in the event payload contains the Macrobank client UUID. This is the recommended way to determine which Macrobank client the user belongs to.

Alternative methods (if macrobank_client_id is not available):

Via WorkOS Organization:

Use workos_org_id from the event

Query WorkOS organization API to get the macrobank-client-id custom attribute

Via Macrobank remote_user:

Query Macrobank remote_users by external_id = gemba_services_user_id

Get the existing remote_user.client_id (INT) which links to Macrobank clients table

object
source
required
string
Source service identifier

Allowed values:
"identity-service"
event_type
required
string
Event type identifier

Allowed values:
"user.updated"
gemba_services_user_id
required
string
format: uuid
Unique gemba-services user ID (UUID). This is used as the external_id in Macrobank remote_users table.

workos_user_id
required
string
WorkOS user ID (from WorkOS webhook)

workos_org_id
string
WorkOS organization ID (optional)

macrobank_client_id
string
format: uuid
Macrobank client UUID (optional).

Usage: This is the recommended way to determine which Macrobank client the user belongs to. The Identity Service looks this up from the organization_mappings table using workos_org_id.

If not provided, use workos_org_id to query WorkOS organization API for the macrobank-client-id custom attribute.

object
Updated user profile data (JSON object). Contains email, first_name, last_name, and other metadata.

Field Mappings to Macrobank:

email → remote_user.email (or remote_user.CliLogin if email not available)

first_name → DocDataRemoteAccount.Name (maps to remote_user.FirstName)

last_name → DocDataRemoteAccount.Surname (maps to remote_user.LastName)

Update Behavior:

Macrobank should update these fields when present in profile_data

WorkOS is the source of truth for user identity data

Macrobank mirrors these fields for legacy system compatibility

email
string
format: email
User email address (updates Macrobank remote_user.email)

first_name
string
User first name (updates Macrobank DocDataRemoteAccount.Name)

last_name
string
User last name (updates Macrobank DocDataRemoteAccount.Surname)

Additional properties are allowed.
timestamp
required
string
format: date-time
ISO 8601 timestamp when the event was published

Additional properties are allowed.
object
key
string
Kafka message key for partitioning. Uses gemba_services_user_id to ensure ordered processing per user.

#identity
Examples
#1 Example - User Updated Example
Example user.updated event
{ "source": "identity-service", "event_type": "user.updated", "gemba_services_user_id": "550e8400-e29b-41d4-a716-446655440000", "workos_user_id": "user_01HZJXKQ8N7X9Y2Z3A4B5C6D7", "workos_org_id": "org_01HZJXKQ8N7X9Y2Z3A4B5C6D7", "macrobank_client_id": "bd73b0c9-5816-da4f-27e5-a9bd2736f41c", "profile_data": { "email": "user.updated@example.com", "first_name": "Jane", "last_name": "Smith", "updated_via": "workos_webhook" }, "timestamp": "2024-01-15T11:45:00Z" }
SEND ${{environment}}-identity-commands
Channel for user identity events published by the Identity Service.

The Identity Service publishes user events after processing WorkOS webhooks. These events are consumed by Macrobank to create/update remote_user records.

Events include the gemba_services_user_id as the external ID for Macrobank.

Topic format: {environment}-identity-commands Examples:

identity-commands (development)

testing-identity-commands

production-identity-commands

Event Ordering: All user-related events (user.created, user.updated, user.deleted, user.suspended) are published to a single topic to maintain ordering guarantees. Events are partitioned by gemba_services_user_id to ensure all events for the same user are processed in order.

Partition key: gemba_services_user_id to ensure ordered processing per user.
Publish user.deleted event
Published by Identity Service when a WorkOS user is deleted. The event is triggered by a WorkOS webhook. Macrobank consumes this event to deactivate or remove the corresponding remote_user record.

Operation IDpublishUserDeleted
Available only on servers:
- testing
- production
object
topic
${{environment}}-identity-commands
partitions
10
replicas
3
- #identity
Accepts the following message:
User Deleted Event
Event published when a user is deleted in WorkOS
application/json
Message IDuserDeleted
Published by the Identity Service when a WorkOS user is deleted.

This event is triggered by a WorkOS user.deleted webhook. The Identity Service:

Looks up the existing gemba_services_user_id mapping

Publishes this event to Kafka

Macrobank consumes this event to deactivate or remove the corresponding remote_user record.

Note: The user mapping in user_profile_mappings table is not deleted to maintain audit trail and historical references. The gemba_services_user_id remains valid for historical data integrity.

Matching WorkOS User to Macrobank Client

The macrobank_client_id field in the event payload contains the Macrobank client UUID. This is the recommended way to determine which Macrobank client the user belonged to.

Alternative methods (if macrobank_client_id is not available):

Via WorkOS Organization:

Use workos_org_id from the event

Query WorkOS organization API to get the macrobank-client-id custom attribute

Via Macrobank remote_user:

Query Macrobank remote_users by external_id = gemba_services_user_id

Get the existing remote_user.client_id (INT) which links to Macrobank clients table

object
source
required
string
Source service identifier

Allowed values:
"identity-service"
event_type
required
string
Event type identifier

Allowed values:
"user.deleted"
gemba_services_user_id
required
string
format: uuid
Unique gemba-services user ID (UUID). This is the external_id used in Macrobank remote_users table.

workos_user_id
required
string
WorkOS user ID (from WorkOS webhook)

workos_org_id
string
WorkOS organization ID (optional)

macrobank_client_id
string
format: uuid
Macrobank client UUID (optional).

Usage: This is the recommended way to determine which Macrobank client the user belonged to. The Identity Service looks this up from the organization_mappings table using workos_org_id.

If not provided, use workos_org_id to query WorkOS organization API for the macrobank-client-id custom attribute.

timestamp
required
string
format: date-time
ISO 8601 timestamp when the event was published

Additional properties are allowed.
object
key
string
Kafka message key for partitioning. Uses gemba_services_user_id to ensure ordered processing per user.

#identity
Examples
#1 Example - User Deleted Example
Example user.deleted event
{ "source": "identity-service", "event_type": "user.deleted", "gemba_services_user_id": "550e8400-e29b-41d4-a716-446655440000", "workos_user_id": "user_01HZJXKQ8N7X9Y2Z3A4B5C6D7", "workos_org_id": "org_01HZJXKQ8N7X9Y2Z3A4B5C6D7", "macrobank_client_id": "bd73b0c9-5816-da4f-27e5-a9bd2736f41c", "timestamp": "2024-01-15T12:00:00Z" }
SEND ${{environment}}-identity-commands
Channel for user identity events published by the Identity Service.

The Identity Service publishes user events after processing WorkOS webhooks. These events are consumed by Macrobank to create/update remote_user records.

Events include the gemba_services_user_id as the external ID for Macrobank.

Topic format: {environment}-identity-commands Examples:

identity-commands (development)

testing-identity-commands

production-identity-commands

Event Ordering: All user-related events (user.created, user.updated, user.deleted, user.suspended) are published to a single topic to maintain ordering guarantees. Events are partitioned by gemba_services_user_id to ensure all events for the same user are processed in order.

Partition key: gemba_services_user_id to ensure ordered processing per user.
Publish user.suspended event
Published by Identity Service when a WorkOS user is suspended. The event is triggered by a WorkOS webhook. Macrobank consumes this event to suspend or deactivate the corresponding remote_user record.

Operation IDpublishUserSuspended
Available only on servers:
- testing
- production
object
topic
${{environment}}-identity-commands
partitions
10
replicas
3
- #identity
Accepts the following message:
User Suspended Event
Event published when a user is suspended in WorkOS
application/json
Message IDuserSuspended
Published by the Identity Service when a WorkOS user is suspended.

This event is triggered by a WorkOS user.suspended webhook. The Identity Service:

Looks up the existing gemba_services_user_id mapping

Publishes this event to Kafka

Macrobank consumes this event to suspend or deactivate the corresponding remote_user record.

Note: Suspension is typically a temporary state. The user mapping remains active in the user_profile_mappings table. If the user is later unsuspended, a user.updated event will be published.

Matching WorkOS User to Macrobank Client

The macrobank_client_id field in the event payload contains the Macrobank client UUID. This is the recommended way to determine which Macrobank client the user belongs to.

Alternative methods (if macrobank_client_id is not available):

Via WorkOS Organization:

Use workos_org_id from the event

Query WorkOS organization API to get the macrobank-client-id custom attribute

Via Macrobank remote_user:

Query Macrobank remote_users by external_id = gemba_services_user_id

Get the existing remote_user.client_id (INT) which links to Macrobank clients table

object
source
required
string
Source service identifier

Allowed values:
"identity-service"
event_type
required
string
Event type identifier

Allowed values:
"user.suspended"
gemba_services_user_id
required
string
format: uuid
Unique gemba-services user ID (UUID). This is the external_id used in Macrobank remote_users table.

workos_user_id
required
string
WorkOS user ID (from WorkOS webhook)

workos_org_id
string
WorkOS organization ID (optional)

macrobank_client_id
string
format: uuid
Macrobank client UUID (optional).

Usage: This is the recommended way to determine which Macrobank client the user belongs to. The Identity Service looks this up from the organization_mappings table using workos_org_id.

If not provided, use workos_org_id to query WorkOS organization API for the macrobank-client-id custom attribute.

timestamp
required
string
format: date-time
ISO 8601 timestamp when the event was published

Additional properties are allowed.
object
key
string
Kafka message key for partitioning. Uses gemba_services_user_id to ensure ordered processing per user.

#identity
Examples
#1 Example - User Suspended Example
Example user.suspended event
{ "source": "identity-service", "event_type": "user.suspended", "gemba_services_user_id": "550e8400-e29b-41d4-a716-446655440000", "workos_user_id": "user_01HZJXKQ8N7X9Y2Z3A4B5C6D7", "workos_org_id": "org_01HZJXKQ8N7X9Y2Z3A4B5C6D7", "macrobank_client_id": "bd73b0c9-5816-da4f-27e5-a9bd2736f41c", "timestamp": "2024-01-15T12:15:00Z" }
RECEIVE ${{environment}}-identity-events
Channel for Macrobank events consumed by the Identity Service.

The Identity Service consumes events from Macrobank to provision and synchronize WorkOS organizations and user permissions. Events are published by Macrobank CDC when client or permission changes occur.

Topic format: {environment}-identity-events Examples:

testing-identity-events

production-identity-events

Note: These events may be published to separate topics (client.created, client.updated, permissions.updated) depending on the Macrobank CDC configuration.
Subscribe to client.created events
Consumes Macrobank client.created events to provision WorkOS organizations. When a new client is created in Macrobank, the Identity Service provisions a corresponding WorkOS organization and stores the mapping.

Operation IDsubscribeClientCreated
Available only on servers:
- testing
- production
object
topic
${{environment}}-identity-events
partitions
10
replicas
3
- #identity
Accepts the following message:
Client Created Event
Event published when a new client is created in Macrobank
application/json
Message IDclientCreated
Published by Macrobank CDC when a new client is created.

The Identity Service consumes this event to:

Provision a corresponding WorkOS organization

Store the mapping between Macrobank client_id and WorkOS org_id

Set WorkOS organization metadata with the Macrobank client ID

Macrobank is the source of truth for clients. This event is published via CDC when a new client record is created in the Macrobank database.

object
event_type
required
string
Event type identifier

Allowed values:
"client.created"
client_id
required
string
Macrobank client ID (GUID)

client_name
string
Client name

domain
string
Client domain (for white-label clients)

source
string
Event source (e.g., "macrobank", "macrobank-cdc")

timestamp
string
format: date-time
ISO 8601 timestamp when the event was published

Additional properties are allowed.
object
key
string
Kafka message key for partitioning. Typically uses client_id to ensure ordered processing per client.

#identity
Examples
#1 Example - Client Created Example
Example client.created event
{ "event_type": "client.created", "client_id": "bd73b0c9-5816-da4f-27e5-a9bd2736f41c", "client_name": "Acme Corporation", "domain": "acme.example.com", "source": "macrobank-cdc", "timestamp": "2024-01-15T09:00:00Z" }
RECEIVE ${{environment}}-identity-events
Channel for Macrobank events consumed by the Identity Service.

The Identity Service consumes events from Macrobank to provision and synchronize WorkOS organizations and user permissions. Events are published by Macrobank CDC when client or permission changes occur.

Topic format: {environment}-identity-events Examples:

testing-identity-events

production-identity-events

Note: These events may be published to separate topics (client.created, client.updated, permissions.updated) depending on the Macrobank CDC configuration.
Subscribe to client.updated events
Consumes Macrobank client.updated events to update WorkOS organizations. When a client is updated in Macrobank, the Identity Service updates the corresponding WorkOS organization.

Operation IDsubscribeClientUpdated
Available only on servers:
- testing
- production
object
topic
${{environment}}-identity-events
partitions
10
replicas
3
- #identity
Accepts the following message:
Client Updated Event
Event published when a client is updated in Macrobank
application/json
Message IDclientUpdated
Published by Macrobank CDC when a client is updated.

The Identity Service consumes this event to:

Look up the corresponding WorkOS organization using the mapping table

Update the WorkOS organization (name, domains, metadata)

Macrobank is the source of truth for clients. This event is published via CDC when a client record is updated in the Macrobank database.

object
event_type
required
string
Event type identifier

Allowed values:
"client.updated"
client_id
required
string
Macrobank client ID (GUID)

client_name
string
Updated client name

domain
string
Updated client domain (for white-label clients)

source
string
Event source (e.g., "macrobank", "macrobank-cdc")

timestamp
string
format: date-time
ISO 8601 timestamp when the event was published

Additional properties are allowed.
object
key
string
Kafka message key for partitioning. Typically uses client_id to ensure ordered processing per client.

#identity
Examples
#1 Example - Client Updated Example
Example client.updated event
{ "event_type": "client.updated", "client_id": "bd73b0c9-5816-da4f-27e5-a9bd2736f41c", "client_name": "Acme Corporation Ltd", "domain": "acme-new.example.com", "source": "macrobank-cdc", "timestamp": "2024-01-15T10:15:00Z" }
RECEIVE ${{environment}}-identity-events
Channel for Macrobank events consumed by the Identity Service.

The Identity Service consumes events from Macrobank to provision and synchronize WorkOS organizations and user permissions. Events are published by Macrobank CDC when client or permission changes occur.

Topic format: {environment}-identity-events Examples:

testing-identity-events

production-identity-events

Note: These events may be published to separate topics (client.created, client.updated, permissions.updated) depending on the Macrobank CDC configuration.
Subscribe to permissions.updated events
Consumes Macrobank permissions.updated events to sync permissions to WorkOS. When user permissions are updated in Macrobank, the Identity Service updates the corresponding WorkOS user metadata.

Operation IDsubscribePermissionsUpdated
Available only on servers:
- testing
- production
object
topic
${{environment}}-identity-events
partitions
10
replicas
3
- #identity
Accepts the following message:
Permissions Updated Event
Event published when user permissions are updated in Macrobank
application/json
Message IDpermissionsUpdated
Published by Macrobank CDC when user permissions are updated.

The Identity Service consumes this event to:

Look up the WorkOS user ID from external_id (gemba_services_user_id)

Update WorkOS user metadata with permission data

User Identification:

Macrobank uses external_id field in remote_users table to store gemba_services_user_id

The Identity Service looks up workos_user_id from user_profile_mappings table using gemba_services_user_id

This provides a direct mapping without needing reverse lookups or additional tables

Macrobank is the source of truth for permissions. This event is published via CDC when permission records are updated in the Macrobank database.

object
event_type
required
string
Event type identifier

Allowed values:
"permissions.updated"
external_id
required
string
format: uuid
gemba_services_user_id (UUID).

This is the same value stored in Macrobank remote_users.external_id and user_profile_mappings.gemba_services_user_id. The Identity Service uses this to look up the corresponding workos_user_id from the user_profile_mappings table.

permission_set_id
string
Permission set ID

array<string>
Array of permission strings

Items:
string
source
string
Event source (e.g., "macrobank", "macrobank-cdc")

timestamp
string
format: date-time
ISO 8601 timestamp when the event was published

Additional properties are allowed.
object
key
string
Kafka message key for partitioning. Uses external_id (gemba_services_user_id) to ensure ordered processing per user.

#identity
Examples
#1 Example - Permissions Updated Example
Example permissions.updated event
{ "event_type": "permissions.updated", "external_id": "550e8400-e29b-41d4-a716-446655440000", "permission_set_id": "premium-user", "permissions": [ "transactions.view", "transactions.create", "accounts.view" ], "source": "macrobank-cdc", "timestamp": "2024-01-15T12:00:00Z" }

Messages

#1Client Notification Command
Command to send notification to a client
- application/json
Message IDClientNotification
object
type
required
string
Notification event type

Allowed values:
"CLIENT_NOTIFICATION"
notificationId
string
format: uuid
Optional unique notification identifier

correlationId
string
Optional correlation ID for tracking

required
object
required
oneOf
object
userId
required
string
format: uuid
Target user ID

clientId
required
string
format: uuid
Client ID

array<string>
Delivery channels

Items:
string
Additional properties are allowed.
object
email
required
string
format: email
Client email address

Additional properties are allowed.
object
sms
required
string
Client SMS number

Additional properties are allowed.
template
required
string
Notification template identifier

Allowed values:
"PROVIDE_AML_DOCUMENTS"
"DORMANT_ACCOUNT_VERIFICATION"
"OUTGOING_PAYMENT_SENT"
oneOf
object [PROVIDE_AML_DOCUMENTS Data]
Data schema for PROVIDE_AML_DOCUMENTS template

url
required
string
format: uri
URL for document submission

transactionId
required
string
Transaction identifier

counterParty
required
string
Counter party name

clientName
string
Optional client name

Additional properties are allowed.
object [DORMANT_ACCOUNT_VERIFICATION Data]
Data schema for DORMANT_ACCOUNT_VERIFICATION template

url
required
string
format: uri
URL for account verification

transactionId
required
string
Transaction identifier

clientName
string
Optional client name

Additional properties are allowed.
object [OUTGOING_PAYMENT_SENT Data]
Data schema for OUTGOING_PAYMENT_SENT template

clientName
required
string
Client name

amountWithCurrency
required
string
Formatted amount with currency (e.g., "1,234.56 GBP")

beneficiaryName
required
string
Beneficiary name

Additional properties are allowed.
object oneOf
White label configuration

object
domain
required
string
White label domain

Additional properties are allowed.
object
clientId
required
string
format: uuid
White label client ID

Additional properties are allowed.
Additional properties are allowed.
Additional properties are allowed.
Additional properties are allowed.
#notifications
#2Applicant Notification Command
Command to send notification to an applicant (pre-client)
- application/json
Message IDApplicantNotification
object
type
required
string
Notification event type

Allowed values:
"APPLICANT_NOTIFICATION"
notificationId
string
format: uuid
Optional unique notification identifier

correlationId
string
Optional correlation ID for tracking

required
object
required
oneOf
object
email
required
string
format: email
Applicant email address

Additional properties are allowed.
object
sms
required
string
Applicant SMS number

Additional properties are allowed.
object
email
required
string
format: email
Applicant email address

sms
required
string
Applicant SMS number

Additional properties are allowed.
template
required
string
Notification template identifier

Allowed values:
"REMINDER_TO_COMPLETE_ONBOARDING"
"REMINDER_TO_COMPLETE_PAYROLL"
"CREATE_ACCOUNT"
"EMAIL_PHONE_VERIFICATION"
object
Template-specific data

Additional properties are allowed.
object oneOf
White label configuration

object
domain
required
string
White label domain

Additional properties are allowed.
object
clientId
required
string
format: uuid
White label client ID

Additional properties are allowed.
Additional properties are allowed.
Additional properties are allowed.
Additional properties are allowed.
#notifications
#3Internal Notification Command
Command to send internal notifications (admin, support, etc.)
- application/json
Message IDInternalNotification
object
type
required
string
Notification event type

Allowed values:
"INTERNAL_NOTIFICATION"
notificationId
string
format: uuid
Optional unique notification identifier

correlationId
string
Optional correlation ID for tracking

required
object
required
oneOf
object
staffPerson
required
string
format: email
Staff member email address

array<string>
Delivery channels

Items:
string
Allowed values:
"email"
"sms"
"slack"
Additional properties are allowed.
object
slackChannel
required
string
Slack channel name

Additional properties are allowed.
template
required
string
Notification template identifier

Allowed values:
"NEW_APPLICANT_IN_HOLD"
object
Template-specific data

Additional properties are allowed.
Additional properties are allowed.
Additional properties are allowed.
#notifications
#4Company Status Event
Event published when a company's registry status is updated and requires action
- application/json
Message IDCompanyStatus
object
clientId
required
string
format: uuid
Macrobank client ID

companyNumber
required
string
non-empty
Company registration number

country
required
string
Company registry country code

Allowed values:
"GBR"
"IMN"
action
required
string
Required action based on company status:

fully_frozen: GBR company in liquidation (complete account freeze)

blocked_on_debit: GBR company in administration (block debit transactions)

block: IMN company dissolved or other blocking status

Allowed values:
"fully_frozen"
"blocked_on_debit"
"block"
registryStatus
required
string
non-empty
Company status from registry (e.g., "liquidation", "administration", "dissolved")

registryStatusDetail
required
string
Additional status detail from registry (e.g., "active-proposal-to-strike-off")

applicantId
string
Associated applicant ID if available

companyName
string
Company name from registry

timestamp
required
string
format: date-time
Event timestamp (ISO 8601)

correlationId
string
Optional correlation ID for tracking

source
required
string
Source service that published this event

Allowed values:
"job-company"
Additional properties are allowed.
#company-status
#5CDC Event Message
Change Data Capture event published when transfer statuses change in Macrobank
- application/json
Message IDCDCEvent
CDC events are published when transfer statuses change in the Macrobank database. The CDC service monitors SQL Server change tracking tables and publishes events to Kafka for downstream consumers.

Message Structure

The message consists of:

Value: Base64-encoded JSON payload containing the transfer details

Headers: Kafka headers with routing metadata (clientId, accountId, type)

Event Types

The type header indicates the event type:

transfer.outgoing.changed - Outgoing transfer status changed (sender perspective)

transfer.incoming.created - Incoming transfer created (recipient perspective, internal transfers only)

Payload Types

The Base64-decoded payload contains one of:

InternalTransfer - For transfers between Gemba accounts

InternationalTransfer - For SWIFT/SEPA transfers

UKTransfer - For UK Faster Payments/BACS/CHAPS transfers

Processing

Consumers should:

Read the type header to determine event type

Base64-decode the message value

Parse the JSON payload according to the transfer type

Use clientId and accountId headers for routing/filtering
Payload
string
format: byte
Base64-encoded JSON payload containing the transfer details.

When decoded, the payload is a JSON object matching one of:

InternalTransfer schema (for internal transfers)

InternationalTransfer schema (for international transfers)

UKTransfer schema (for UK transfers)

The specific schema depends on the source document class in the CDC change.
object
clientId
required
string
format: uuid
The Gemba client ID (GUID) for routing the event

accountId
required
string
format: uuid
The Gemba account ID (GUID) associated with the transfer

type
required
string
Event type indicating the nature of the change:

transfer.outgoing.changed: Outgoing transfer status changed

transfer.incoming.created: Incoming transfer created (internal transfers only)

Allowed values:
"transfer.outgoing.changed"
"transfer.incoming.created"
Additional properties are allowed.
object
key
string
Kafka message key for partitioning. Typically the eventType value or a GUID if eventType is not set.
#cdc
#6User Created Event
Event published when a new user is created in WorkOS
- application/json
Message IDUserCreated
Published by the Identity Service when a WorkOS user is created.

This event is triggered by a WorkOS user.created webhook. The Identity Service:

Generates a unique gemba_services_user_id (UUID)

Stores the mapping in the database

Enriches user profile data

Publishes this event to Kafka

Macrobank consumes this event to create the corresponding remote_user record using gemba_services_user_id as the external_id.

Profile Data Mapping

When creating the remote_user record, Macrobank should map the following fields:

email → remote_user.email (or remote_user.CliLogin if email not available)

first_name → DocDataRemoteAccount.Name (maps to remote_user.FirstName)

last_name → DocDataRemoteAccount.Surname (maps to remote_user.LastName)

Matching WorkOS User to Macrobank Client

The macrobank_client_id field in the event payload contains the Macrobank client UUID. This is the recommended way to determine which Macrobank client the user belongs to.

Alternative methods (if macrobank_client_id is not available):

Via WorkOS Organization:

Use workos_org_id from the event

Query WorkOS organization API to get the macrobank-client-id custom attribute

This gives you the Macrobank client UUID

Via Macrobank remote_user (After Creation):

After creating remote_user with external_id = gemba_services_user_id

Query Macrobank remote_users table by external_id

Get remote_user.client_id (INT) which links to Macrobank clients table

Note: The Identity Service looks up macrobank_client_id from the organization_mappings table using workos_org_id. This mapping is established when Identity Service provisions WorkOS organizations from Macrobank client.created events.
object
source
required
string
Source service identifier

Allowed values:
"identity-service"
event_type
required
string
Event type identifier

Allowed values:
"user.created"
gemba_services_user_id
required
string
format: uuid
Unique gemba-services user ID (UUID) generated by Identity Service. This is used as the external_id in Macrobank remote_users table.

workos_user_id
required
string
WorkOS user ID (from WorkOS webhook)

workos_org_id
string
WorkOS organization ID (optional)

macrobank_client_id
string
format: uuid
Macrobank client UUID (optional).

Usage: This is the recommended way to determine which Macrobank client the user belongs to. The Identity Service looks this up from the organization_mappings table using workos_org_id.

If not provided, use workos_org_id to query WorkOS organization API for the macrobank-client-id custom attribute.

object
Enriched user profile data (JSON object). Contains email, first_name, last_name, and other metadata.

Field Mappings to Macrobank:

email → remote_user.email (or remote_user.CliLogin if email not available)

first_name → DocDataRemoteAccount.Name (maps to remote_user.FirstName)

last_name → DocDataRemoteAccount.Surname (maps to remote_user.LastName)

email
string
format: email
User email address (maps to Macrobank remote_user.email)

first_name
string
User first name (maps to Macrobank DocDataRemoteAccount.Name)

last_name
string
User last name (maps to Macrobank DocDataRemoteAccount.Surname)

Additional properties are allowed.
timestamp
required
string
format: date-time
ISO 8601 timestamp when the event was published

Additional properties are allowed.
object
key
string
Kafka message key for partitioning. Uses gemba_services_user_id to ensure ordered processing per user.
#identity
#7User Updated Event
Event published when a user is updated in WorkOS
- application/json
Message IDUserUpdated
Published by the Identity Service when a WorkOS user is updated.

This event is triggered by a WorkOS user.updated webhook. The Identity Service:

Retrieves the existing gemba_services_user_id mapping

Updates the profile data

Publishes this event to Kafka

Macrobank consumes this event to update the corresponding remote_user record.

Profile Data Updates

Users can update their profile information in WorkOS, including:

email - Email address

first_name - First name

last_name - Last name

Other metadata fields

When Macrobank receives a user.updated event:

Email Updates:

Update remote_user.email (or remote_user.CliLogin if email is not available)

Name Updates:

Update DocDataRemoteAccount.Name with first_name (maps to remote_user.FirstName)

Update DocDataRemoteAccount.Surname with last_name (maps to remote_user.LastName)

Compliance Considerations:

WorkOS is the source of truth for user identities, so Macrobank should update the fields

Name changes may require compliance/KYC review depending on regulatory requirements

Macrobank may need to flag significant name changes for manual review

Consider triggering re-verification workflows for substantial name changes (e.g., complete name replacement)

Matching WorkOS User to Macrobank Client

The macrobank_client_id field in the event payload contains the Macrobank client UUID. This is the recommended way to determine which Macrobank client the user belongs to.

Alternative methods (if macrobank_client_id is not available):

Via WorkOS Organization:

Use workos_org_id from the event

Query WorkOS organization API to get the macrobank-client-id custom attribute

Via Macrobank remote_user:

Query Macrobank remote_users by external_id = gemba_services_user_id

Get the existing remote_user.client_id (INT) which links to Macrobank clients table
object
source
required
string
Source service identifier

Allowed values:
"identity-service"
event_type
required
string
Event type identifier

Allowed values:
"user.updated"
gemba_services_user_id
required
string
format: uuid
Unique gemba-services user ID (UUID). This is used as the external_id in Macrobank remote_users table.

workos_user_id
required
string
WorkOS user ID (from WorkOS webhook)

workos_org_id
string
WorkOS organization ID (optional)

macrobank_client_id
string
format: uuid
Macrobank client UUID (optional).

Usage: This is the recommended way to determine which Macrobank client the user belongs to. The Identity Service looks this up from the organization_mappings table using workos_org_id.

If not provided, use workos_org_id to query WorkOS organization API for the macrobank-client-id custom attribute.

object
Updated user profile data (JSON object). Contains email, first_name, last_name, and other metadata.

Field Mappings to Macrobank:

email → remote_user.email (or remote_user.CliLogin if email not available)

first_name → DocDataRemoteAccount.Name (maps to remote_user.FirstName)

last_name → DocDataRemoteAccount.Surname (maps to remote_user.LastName)

Update Behavior:

Macrobank should update these fields when present in profile_data

WorkOS is the source of truth for user identity data

Macrobank mirrors these fields for legacy system compatibility

email
string
format: email
User email address (updates Macrobank remote_user.email)

first_name
string
User first name (updates Macrobank DocDataRemoteAccount.Name)

last_name
string
User last name (updates Macrobank DocDataRemoteAccount.Surname)

Additional properties are allowed.
timestamp
required
string
format: date-time
ISO 8601 timestamp when the event was published

Additional properties are allowed.
object
key
string
Kafka message key for partitioning. Uses gemba_services_user_id to ensure ordered processing per user.
#identity
#8User Deleted Event
Event published when a user is deleted in WorkOS
- application/json
Message IDUserDeleted
Published by the Identity Service when a WorkOS user is deleted.

This event is triggered by a WorkOS user.deleted webhook. The Identity Service:

Looks up the existing gemba_services_user_id mapping

Publishes this event to Kafka

Macrobank consumes this event to deactivate or remove the corresponding remote_user record.

Note: The user mapping in user_profile_mappings table is not deleted to maintain audit trail and historical references. The gemba_services_user_id remains valid for historical data integrity.

Matching WorkOS User to Macrobank Client

The macrobank_client_id field in the event payload contains the Macrobank client UUID. This is the recommended way to determine which Macrobank client the user belonged to.

Alternative methods (if macrobank_client_id is not available):

Via WorkOS Organization:

Use workos_org_id from the event

Query WorkOS organization API to get the macrobank-client-id custom attribute

Via Macrobank remote_user:

Query Macrobank remote_users by external_id = gemba_services_user_id

Get the existing remote_user.client_id (INT) which links to Macrobank clients table
object
source
required
string
Source service identifier

Allowed values:
"identity-service"
event_type
required
string
Event type identifier

Allowed values:
"user.deleted"
gemba_services_user_id
required
string
format: uuid
Unique gemba-services user ID (UUID). This is the external_id used in Macrobank remote_users table.

workos_user_id
required
string
WorkOS user ID (from WorkOS webhook)

workos_org_id
string
WorkOS organization ID (optional)

macrobank_client_id
string
format: uuid
Macrobank client UUID (optional).

Usage: This is the recommended way to determine which Macrobank client the user belonged to. The Identity Service looks this up from the organization_mappings table using workos_org_id.

If not provided, use workos_org_id to query WorkOS organization API for the macrobank-client-id custom attribute.

timestamp
required
string
format: date-time
ISO 8601 timestamp when the event was published

Additional properties are allowed.
object
key
string
Kafka message key for partitioning. Uses gemba_services_user_id to ensure ordered processing per user.
#identity
#9User Suspended Event
Event published when a user is suspended in WorkOS
- application/json
Message IDUserSuspended
Published by the Identity Service when a WorkOS user is suspended.

This event is triggered by a WorkOS user.suspended webhook. The Identity Service:

Looks up the existing gemba_services_user_id mapping

Publishes this event to Kafka

Macrobank consumes this event to suspend or deactivate the corresponding remote_user record.

Note: Suspension is typically a temporary state. The user mapping remains active in the user_profile_mappings table. If the user is later unsuspended, a user.updated event will be published.

Matching WorkOS User to Macrobank Client

The macrobank_client_id field in the event payload contains the Macrobank client UUID. This is the recommended way to determine which Macrobank client the user belongs to.

Alternative methods (if macrobank_client_id is not available):

Via WorkOS Organization:

Use workos_org_id from the event

Query WorkOS organization API to get the macrobank-client-id custom attribute

Via Macrobank remote_user:

Query Macrobank remote_users by external_id = gemba_services_user_id

Get the existing remote_user.client_id (INT) which links to Macrobank clients table
object
source
required
string
Source service identifier

Allowed values:
"identity-service"
event_type
required
string
Event type identifier

Allowed values:
"user.suspended"
gemba_services_user_id
required
string
format: uuid
Unique gemba-services user ID (UUID). This is the external_id used in Macrobank remote_users table.

workos_user_id
required
string
WorkOS user ID (from WorkOS webhook)

workos_org_id
string
WorkOS organization ID (optional)

macrobank_client_id
string
format: uuid
Macrobank client UUID (optional).

Usage: This is the recommended way to determine which Macrobank client the user belongs to. The Identity Service looks this up from the organization_mappings table using workos_org_id.

If not provided, use workos_org_id to query WorkOS organization API for the macrobank-client-id custom attribute.

timestamp
required
string
format: date-time
ISO 8601 timestamp when the event was published

Additional properties are allowed.
object
key
string
Kafka message key for partitioning. Uses gemba_services_user_id to ensure ordered processing per user.
#identity
#10Client Created Event
Event published when a new client is created in Macrobank
- application/json
Message IDClientCreated
Published by Macrobank CDC when a new client is created.

The Identity Service consumes this event to:

Provision a corresponding WorkOS organization

Store the mapping between Macrobank client_id and WorkOS org_id

Set WorkOS organization metadata with the Macrobank client ID

Macrobank is the source of truth for clients. This event is published via CDC when a new client record is created in the Macrobank database.
object
event_type
required
string
Event type identifier

Allowed values:
"client.created"
client_id
required
string
Macrobank client ID (GUID)

client_name
string
Client name

domain
string
Client domain (for white-label clients)

source
string
Event source (e.g., "macrobank", "macrobank-cdc")

timestamp
string
format: date-time
ISO 8601 timestamp when the event was published

Additional properties are allowed.
object
key
string
Kafka message key for partitioning. Typically uses client_id to ensure ordered processing per client.
#identity
#11Client Updated Event
Event published when a client is updated in Macrobank
- application/json
Message IDClientUpdated
Published by Macrobank CDC when a client is updated.

The Identity Service consumes this event to:

Look up the corresponding WorkOS organization using the mapping table

Update the WorkOS organization (name, domains, metadata)

Macrobank is the source of truth for clients. This event is published via CDC when a client record is updated in the Macrobank database.
object
event_type
required
string
Event type identifier

Allowed values:
"client.updated"
client_id
required
string
Macrobank client ID (GUID)

client_name
string
Updated client name

domain
string
Updated client domain (for white-label clients)

source
string
Event source (e.g., "macrobank", "macrobank-cdc")

timestamp
string
format: date-time
ISO 8601 timestamp when the event was published

Additional properties are allowed.
object
key
string
Kafka message key for partitioning. Typically uses client_id to ensure ordered processing per client.
#identity
#12Permissions Updated Event
Event published when user permissions are updated in Macrobank
- application/json
Message IDPermissionsUpdated
Published by Macrobank CDC when user permissions are updated.

The Identity Service consumes this event to:

Look up the WorkOS user ID from external_id (gemba_services_user_id)

Update WorkOS user metadata with permission data

User Identification:

Macrobank uses external_id field in remote_users table to store gemba_services_user_id

The Identity Service looks up workos_user_id from user_profile_mappings table using gemba_services_user_id

This provides a direct mapping without needing reverse lookups or additional tables

Macrobank is the source of truth for permissions. This event is published via CDC when permission records are updated in the Macrobank database.
object
event_type
required
string
Event type identifier

Allowed values:
"permissions.updated"
external_id
required
string
format: uuid
gemba_services_user_id (UUID).

This is the same value stored in Macrobank remote_users.external_id and user_profile_mappings.gemba_services_user_id. The Identity Service uses this to look up the corresponding workos_user_id from the user_profile_mappings table.

permission_set_id
string
Permission set ID

array<string>
Array of permission strings

Items:
string
source
string
Event source (e.g., "macrobank", "macrobank-cdc")

timestamp
string
format: date-time
ISO 8601 timestamp when the event was published

Additional properties are allowed.
object
key
string
Kafka message key for partitioning. Uses external_id (gemba_services_user_id) to ensure ordered processing per user.
#identity

Servers

Security:

Security:

Operations

SEND ${{environment}}-notifications

Examples

#1 Example - MacrobankOutgoingPaymentExample

Examples

This example has been generated automatically.

Examples

This example has been generated automatically.

RECEIVE ${{environment}}-notifications

Examples

#1 Example - MacrobankOutgoingPaymentExample

Examples

This example has been generated automatically.

Examples

This example has been generated automatically.

SEND ${{environment}}-company-status

Examples

#1 Example - GBR Company in Liquidation

#2 Example - GBR Company in Administration

#3 Example - IMN Company Dissolved

RECEIVE ${{environment}}-company-status

Examples

#1 Example - GBR Company in Liquidation

#2 Example - GBR Company in Administration

#3 Example - IMN Company Dissolved

SEND ${{environment}}-cdc-events

Message Structure

Event Types

Payload Types

Processing

Examples

#1 Example - Internal Transfer - Outgoing Changed

#2 Example - Internal Transfer - Incoming Created

#3 Example - International Transfer - Outgoing Changed

#4 Example - UK Transfer - Outgoing Changed

#1 Example - Internal Transfer - Outgoing Changed

#2 Example - Internal Transfer - Incoming Created

#3 Example - International Transfer - Outgoing Changed

#4 Example - UK Transfer - Outgoing Changed

RECEIVE ${{environment}}-cdc-events

Use Cases

Processing Guidelines

Message Structure

Event Types

Payload Types

Processing

Examples

#1 Example - Internal Transfer - Outgoing Changed

#2 Example - Internal Transfer - Incoming Created

#3 Example - International Transfer - Outgoing Changed

#4 Example - UK Transfer - Outgoing Changed

#1 Example - Internal Transfer - Outgoing Changed

#2 Example - Internal Transfer - Incoming Created

#3 Example - International Transfer - Outgoing Changed

#4 Example - UK Transfer - Outgoing Changed

SEND ${{environment}}-identity-commands

Profile Data Mapping

Matching WorkOS User to Macrobank Client

Examples

#1 Example - User Created Example

SEND ${{environment}}-identity-commands

Profile Data Updates

Matching WorkOS User to Macrobank Client

Examples

#1 Example - User Updated Example

SEND ${{environment}}-identity-commands

Matching WorkOS User to Macrobank Client

Examples

#1 Example - User Deleted Example

SEND ${{environment}}-identity-commands

Matching WorkOS User to Macrobank Client

Examples

#1 Example - User Suspended Example

RECEIVE ${{environment}}-identity-events

Examples

#1 Example - Client Created Example

RECEIVE ${{environment}}-identity-events