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
  • #card-payouts
  • #support

Servers

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

    Testing environment Kafka cluster

    object
    string
    required

    Environment name used in topic naming (e.g., testing-notifications)

    Security:
    security.protocol:PLAINTEXT
    object
    • #environment
  • kafka://bootstrap.production-kafka-cluster.europe-west2.managedkafka.services-prod-437113.cloud.goog:9092/kafkaproduction

    Production Kafka cluster

    object
    string
    required

    Environment name used in topic naming (e.g., production-notifications)

    Security:
    security.protocol:PLAINTEXT
    object
    • #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:

    object
    • #notifications

    Accepts one of the following messages:

    • #0Client Notification Command

      Command to send notification to a client

      Message IDclientNotification
      object
      • #notifications

      Examples

    • #1Applicant Notification Command

      Command to send notification to an applicant (pre-client)

      Message IDapplicantNotification
      object
      • #notifications

      Examples

    • #2Internal Notification Command

      Command to send internal notifications (admin, support, etc.)

      Message IDinternalNotification
      object
      • #notifications

      Examples

  • 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:

    object
    • #notifications

    Accepts one of the following messages:

    • #0Client Notification Command

      Command to send notification to a client

      Message IDclientNotification
      object
      • #notifications

      Examples

    • #1Applicant Notification Command

      Command to send notification to an applicant (pre-client)

      Message IDapplicantNotification
      object
      • #notifications

      Examples

    • #2Internal Notification Command

      Command to send internal notifications (admin, support, etc.)

      Message IDinternalNotification
      object
      • #notifications

      Examples

  • 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:

    object
    • #company-status

    Accepts the following message:

    Company Status Event

    Event published when a company's registry status is updated and requires action

    Message IDcompanyStatusMessage
    object
    • #company-status

    Examples

  • 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:

    object
    • #company-status

    Accepts the following message:

    Company Status Event

    Event published when a company's registry status is updated and requires action

    Message IDcompanyStatusMessage
    object
    • #company-status

    Examples

  • SEND ${{environment}}-card-payouts-aml

    Channel for card payout AML check results. Data originates from CheckMarble webhooks: when an AML analyst reviews a held card payout decision, CheckMarble sends a webhook to the transactions service, which produces the result to this topic. Only final statuses (approved/declined) are published; items still on hold are not sent. Topic format: {environment}-card-payouts-aml Examples:

    • testing-card-payouts-aml
    • production-card-payouts-aml

    Publish card payout AML result

    Published by the transactions service when a CheckMarble webhook is received after an AML analyst reviews a held card payout decision. Only final statuses (approved/declined) are published.

    Operation IDpublishCardPayoutAMLResult

    Available only on servers:

    object
    • #card-payouts

    Accepts the following message:

    Card Payout AML Result

    AML check result for a card payout item, published after an analyst reviews a held decision

    Message IDcardPayoutAMLResult
    object
    object
    • #card-payouts

    Examples

  • RECEIVE ${{environment}}-card-payouts-aml

    Channel for card payout AML check results. Data originates from CheckMarble webhooks: when an AML analyst reviews a held card payout decision, CheckMarble sends a webhook to the transactions service, which produces the result to this topic. Only final statuses (approved/declined) are published; items still on hold are not sent. Topic format: {environment}-card-payouts-aml Examples:

    • testing-card-payouts-aml
    • production-card-payouts-aml

    Subscribe to card payout AML results

    Consume AML check results for card payout items to process approved/declined payouts.

    Operation IDsubscribeCardPayoutAMLResult

    Available only on servers:

    object
    • #card-payouts

    Accepts the following message:

    Card Payout AML Result

    AML check result for a card payout item, published after an analyst reviews a held decision

    Message IDcardPayoutAMLResult
    object
    object
    • #card-payouts

    Examples

  • SEND ${{environment}}-card-payouts-nuvei

    Channel for card payout events to be processed by Nuvei. Data originates from Nuvei webhooks: incoming webhook payloads are produced to this topic for async processing. Topic format: {environment}-card-payouts-nuvei Examples:

    • testing-card-payouts-nuvei
    • production-card-payouts-nuvei

    Publish card payout event to Nuvei

    Published when a Nuvei webhook is received, forwarding the payload for async processing.

    Operation IDpublishCardPayoutNuvei

    Available only on servers:

    object
    • #card-payouts

    Accepts the following message:

    Card Payout Nuvei Message

    Card payout event forwarded to Nuvei for processing

    Message IDcardPayoutNuveiMessage
    object

    Payload forwarded to Nuvei (schema varies by operation)

    object
    • #card-payouts

    Examples

  • RECEIVE ${{environment}}-card-payouts-nuvei

    Channel for card payout events to be processed by Nuvei. Data originates from Nuvei webhooks: incoming webhook payloads are produced to this topic for async processing. Topic format: {environment}-card-payouts-nuvei Examples:

    • testing-card-payouts-nuvei
    • production-card-payouts-nuvei

    Subscribe to card payout Nuvei events

    Consume card payout events for Nuvei processing.

    Operation IDsubscribeCardPayoutNuvei

    Available only on servers:

    object
    • #card-payouts

    Accepts the following message:

    Card Payout Nuvei Message

    Card payout event forwarded to Nuvei for processing

    Message IDcardPayoutNuveiMessage
    object

    Payload forwarded to Nuvei (schema varies by operation)

    object
    • #card-payouts

    Examples

  • 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:

    1. Retrieves the full transfer payload from the database
    2. Base64-encodes the JSON payload
    3. 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:

    object
    • #cdc

    Accepts the following message:

    CDC Event Message

    Change Data Capture event published when transfer statuses change in Macrobank

    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:

    1. Read the type header to determine event type
    2. Base64-decode the message value
    3. Parse the JSON payload according to the transfer type
    4. Use clientId and accountId headers for routing/filtering
    string

    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
    object
    • #cdc

    Examples

  • 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

    1. Idempotency: Events may be delivered more than once. Use the transfer id for deduplication.
    2. Ordering: Events for the same type are ordered within a partition. Different event types may arrive out of order.
    3. Filtering: Use Kafka headers to filter events by clientId, accountId, or type.
    4. Schema Handling: The payload type varies based on the source transfer. Handle InternalTransfer, InternationalTransfer, and UKTransfer schemas.
    Operation IDsubscribeCDCEvent

    Available only on servers:

    object
    • #cdc

    Accepts the following message:

    CDC Event Message

    Change Data Capture event published when transfer statuses change in Macrobank

    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:

    1. Read the type header to determine event type
    2. Base64-decode the message value
    3. Parse the JSON payload according to the transfer type
    4. Use clientId and accountId headers for routing/filtering
    string

    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
    object
    • #cdc

    Examples

  • 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:

    object
    • #identity

    Accepts the following message:

    User Created Event

    Event published when a new user is created in WorkOS

    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:

    1. Generates a unique gemba_services_user_id (UUID)
    2. Stores the mapping in the database
    3. Enriches user profile data
    4. 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):

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

    2. 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
    object
    • #identity

    Examples

  • 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:

    object
    • #identity

    Accepts the following message:

    User Updated Event

    Event published when a user is updated in WorkOS

    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:

    1. Retrieves the existing gemba_services_user_id mapping
    2. Updates the profile data
    3. 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):

    1. Via WorkOS Organization:

      • Use workos_org_id from the event
      • Query WorkOS organization API to get the macrobank-client-id custom attribute

    2. 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
    object
    • #identity

    Examples

  • 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:

    object
    • #identity

    Accepts the following message:

    User Deleted Event

    Event published when a user is deleted in WorkOS

    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:

    1. Looks up the existing gemba_services_user_id mapping
    2. 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):

    1. Via WorkOS Organization:

      • Use workos_org_id from the event
      • Query WorkOS organization API to get the macrobank-client-id custom attribute

    2. 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
    object
    • #identity

    Examples

  • 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:

    object
    • #identity

    Accepts the following message:

    User Suspended Event

    Event published when a user is suspended in WorkOS

    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:

    1. Looks up the existing gemba_services_user_id mapping
    2. 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):

    1. Via WorkOS Organization:

      • Use workos_org_id from the event
      • Query WorkOS organization API to get the macrobank-client-id custom attribute

    2. 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
    object
    • #identity

    Examples

  • 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:

    object
    • #identity

    Accepts the following message:

    Client Created Event

    Event published when a new client is created in Macrobank

    Message IDclientCreated

    Published by Macrobank CDC when a new client is created.

    The Identity Service consumes this event to:

    1. Provision a corresponding WorkOS organization
    2. Store the mapping between Macrobank client_id and WorkOS org_id
    3. 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
    object
    • #identity

    Examples

  • 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:

    object
    • #identity

    Accepts the following message:

    Client Updated Event

    Event published when a client is updated in Macrobank

    Message IDclientUpdated

    Published by Macrobank CDC when a client is updated.

    The Identity Service consumes this event to:

    1. Look up the corresponding WorkOS organization using the mapping table
    2. 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
    object
    • #identity

    Examples

  • 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:

    object
    • #identity

    Accepts the following message:

    Permissions Updated Event

    Event published when user permissions are updated in Macrobank

    Message IDpermissionsUpdated

    Published by Macrobank CDC when user permissions are updated.

    The Identity Service consumes this event to:

    1. Look up the WorkOS user ID from external_id (gemba_services_user_id)
    2. 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
    object
    • #identity

    Examples

  • SEND ${{environment}}-frontapp-incoming

    Channel for FrontApp incoming events consumed by the Support service. Events (e.g. team replies) are produced by a webhook ingress that receives FrontApp HTTP callbacks and publishes to this topic. The Support service consumes messages and sends team replies to customers via Resend. Topic format: {environment}-frontapp-incoming Examples:

    • testing-frontapp-incoming
    • production-frontapp-incoming

    Publish FrontApp event to Support

    Published by the webhook ingress when a FrontApp HTTP callback is received. Payload is the same as the former FrontApp webhook body. Support service consumes and processes team replies (sends to customer via Resend).

    Operation IDpublishFrontappIncoming

    Available only on servers:

    object
    • #support

    Accepts the following message:

    FrontApp Incoming Message

    FrontApp webhook payload (direct message or wrapped event) forwarded for Support processing

    Message IDfrontappIncomingMessage
    oneOf

    Same as former FrontApp webhook body. Exactly one of: direct message (message_uid required) or wrapped event (type, emitted_at, payload required). Support processes direct messages with type "custom" and !is_inbound as team replies (sends to customer via Resend).

    object
    • #support

    Examples

  • RECEIVE ${{environment}}-frontapp-incoming

    Channel for FrontApp incoming events consumed by the Support service. Events (e.g. team replies) are produced by a webhook ingress that receives FrontApp HTTP callbacks and publishes to this topic. The Support service consumes messages and sends team replies to customers via Resend. Topic format: {environment}-frontapp-incoming Examples:

    • testing-frontapp-incoming
    • production-frontapp-incoming

    Subscribe to FrontApp incoming events

    Support service consumes from this topic. Team replies (type custom, is_inbound=false) are sent to customers via Resend.

    Operation IDsubscribeFrontappIncoming

    Available only on servers:

    object
    • #support

    Accepts the following message:

    FrontApp Incoming Message

    FrontApp webhook payload (direct message or wrapped event) forwarded for Support processing

    Message IDfrontappIncomingMessage
    oneOf

    Same as former FrontApp webhook body. Exactly one of: direct message (message_uid required) or wrapped event (type, emitted_at, payload required). Support processes direct messages with type "custom" and !is_inbound as team replies (sends to customer via Resend).

    object
    • #support

    Examples

  • SEND ${{environment}}-resend-incoming

    Channel for Resend incoming events consumed by the Support service. Events (e.g. email.received) are produced by a webhook ingress that receives Resend HTTP callbacks and publishes to this topic. The Support service consumes messages and forwards inbound emails to FrontApp. Topic format: {environment}-resend-incoming Examples:

    • testing-resend-incoming
    • production-resend-incoming

    Publish Resend event to Support

    Published by the webhook ingress when a Resend HTTP callback is received (e.g. email.received). Support service consumes and forwards inbound emails to FrontApp.

    Operation IDpublishResendIncoming

    Available only on servers:

    object
    • #support

    Accepts the following message:

    Resend Incoming Message

    Resend webhook payload (e.g. email.received) forwarded for Support processing

    Message IDresendIncomingMessage
    object
    object
    • #support

    Examples

  • RECEIVE ${{environment}}-resend-incoming

    Channel for Resend incoming events consumed by the Support service. Events (e.g. email.received) are produced by a webhook ingress that receives Resend HTTP callbacks and publishes to this topic. The Support service consumes messages and forwards inbound emails to FrontApp. Topic format: {environment}-resend-incoming Examples:

    • testing-resend-incoming
    • production-resend-incoming

    Subscribe to Resend incoming events

    Support service consumes from this topic. email.received events are processed: full email is retrieved from Resend and forwarded to the FrontApp channel for the domain.

    Operation IDsubscribeResendIncoming

    Available only on servers:

    object
    • #support

    Accepts the following message:

    Resend Incoming Message

    Resend webhook payload (e.g. email.received) forwarded for Support processing

    Message IDresendIncomingMessage
    object
    object
    • #support

    Examples

Messages

  • #1Client Notification Command

    Command to send notification to a client

    Message IDClientNotification
    object
    • #notifications
  • #2Applicant Notification Command

    Command to send notification to an applicant (pre-client)

    Message IDApplicantNotification
    object
    • #notifications
  • #3Internal Notification Command

    Command to send internal notifications (admin, support, etc.)

    Message IDInternalNotification
    object
    • #notifications
  • #4Company Status Event

    Event published when a company's registry status is updated and requires action

    Message IDCompanyStatus
    object
    • #company-status
  • #5Card Payout AML Result

    AML check result for a card payout item, published after an analyst reviews a held decision

    Message IDCardPayoutAMLResult
    object
    object
    • #card-payouts
  • #6Card Payout Nuvei Message

    Card payout event forwarded to Nuvei for processing

    Message IDCardPayoutNuveiMessage
    object

    Payload forwarded to Nuvei (schema varies by operation)

    object
    • #card-payouts
  • #7CDC Event Message

    Change Data Capture event published when transfer statuses change in Macrobank

    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:

    1. Read the type header to determine event type
    2. Base64-decode the message value
    3. Parse the JSON payload according to the transfer type
    4. Use clientId and accountId headers for routing/filtering
    string

    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
    object
    • #cdc
  • #8User Created Event

    Event published when a new user is created in WorkOS

    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:

    1. Generates a unique gemba_services_user_id (UUID)
    2. Stores the mapping in the database
    3. Enriches user profile data
    4. 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):

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

    2. 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
    object
    • #identity
  • #9User Updated Event

    Event published when a user is updated in WorkOS

    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:

    1. Retrieves the existing gemba_services_user_id mapping
    2. Updates the profile data
    3. 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):

    1. Via WorkOS Organization:

      • Use workos_org_id from the event
      • Query WorkOS organization API to get the macrobank-client-id custom attribute

    2. 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
    object
    • #identity
  • #10User Deleted Event

    Event published when a user is deleted in WorkOS

    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:

    1. Looks up the existing gemba_services_user_id mapping
    2. 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):

    1. Via WorkOS Organization:

      • Use workos_org_id from the event
      • Query WorkOS organization API to get the macrobank-client-id custom attribute

    2. 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
    object
    • #identity
  • #11User Suspended Event

    Event published when a user is suspended in WorkOS

    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:

    1. Looks up the existing gemba_services_user_id mapping
    2. 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):

    1. Via WorkOS Organization:

      • Use workos_org_id from the event
      • Query WorkOS organization API to get the macrobank-client-id custom attribute

    2. 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
    object
    • #identity
  • #12Client Created Event

    Event published when a new client is created in Macrobank

    Message IDClientCreated

    Published by Macrobank CDC when a new client is created.

    The Identity Service consumes this event to:

    1. Provision a corresponding WorkOS organization
    2. Store the mapping between Macrobank client_id and WorkOS org_id
    3. 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
    object
    • #identity
  • #13Client Updated Event

    Event published when a client is updated in Macrobank

    Message IDClientUpdated

    Published by Macrobank CDC when a client is updated.

    The Identity Service consumes this event to:

    1. Look up the corresponding WorkOS organization using the mapping table
    2. 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
    object
    • #identity
  • #14Permissions Updated Event

    Event published when user permissions are updated in Macrobank

    Message IDPermissionsUpdated

    Published by Macrobank CDC when user permissions are updated.

    The Identity Service consumes this event to:

    1. Look up the WorkOS user ID from external_id (gemba_services_user_id)
    2. 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
    object
    • #identity
  • #15FrontApp Incoming Message

    FrontApp webhook payload (direct message or wrapped event) forwarded for Support processing

    Message IDFrontappIncomingMessage
    oneOf

    Same as former FrontApp webhook body. Exactly one of: direct message (message_uid required) or wrapped event (type, emitted_at, payload required). Support processes direct messages with type "custom" and !is_inbound as team replies (sends to customer via Resend).

    object
    • #support
  • #16Resend Incoming Message

    Resend webhook payload (e.g. email.received) forwarded for Support processing

    Message IDResendIncomingMessage
    object
    object
    • #support