Skip to main content

Streaming API

The Streaming API is a system-to-system communication channel that uses a pull-based strategy to stream large volumes of event data out of Mambu.

You use event streaming notification templates to define what to publish and when. Your systems then consume those events via the Streaming API.

If you have multiple client applications that need to consume the same events, prefer the Streaming API over webhooks. Webhooks are push-based and optimized for point-to-point delivery. For a comparison, see Webhook notifications.

note

To use the Streaming API, you must have API consumers enabled and configured. See API Consumers in the User Guide and Streaming API Authentication in the API Reference.

Create and manage event streaming notification templates​

Event streaming templates define which events are produced and what payload is delivered through the Streaming API.

To create an event streaming notification template:

  1. Go to Administration > Events Streaming > Templates.
  2. Select Add Notification.
  3. Enter the necessary information (see fields below).
  4. Select Save Changes.

Templates are listed with:

  • State – In Use (at least one notification sent) or Not In Use.
  • Status – Active (can be used) or Inactive (deactivated).

Only templates with Status = Active can produce events.

Permissions​

To manage Streaming templates:

  • Create / edit templates: requires the Manage Events Streaming permission.
  • View templates: users with administration visibility (for example, View Administration Details) or Manage Events Streaming can view the Events Streaming templates.

Template fields​

Name​

  • Must be unique.
  • Leading and trailing spaces are automatically trimmed on save.
  • Maximum length: 255 characters.

Subscription option​

Choose how recipients are subscribed:

  • Opt-out (auto-subscribed): on first save, relevant recipients are automatically subscribed in the background. They can later unsubscribe.
  • Opt-in (manually subscribed): recipients are not subscribed by default. You must subscribe them explicitly.

Streaming templates use the same subscription model as other notification channels, and subscriptions are managed via Notification Requests on the recipient profile.

Target​

The target determines what the event relates to and which events are available.

Supported targets include, for example:

  • Client
  • Group
  • Background process (for example, End of Day)
  • Data access
  • Payment order (when the Payments capability is enabled)
  • Accounting (journal entries)

Notes:

  • Availability of targets and events depends on enabled capabilities and tenant feature toggles.
  • Not all events are available for all targets.

Event trigger​

Choose the event that will trigger the notification. Available events depend on:

  • The selected target, and
  • Enabled capabilities and feature toggles for your tenant.

Compared to email and SMS, event streaming may expose additional event categories when they are enabled.

For an overview of event types, see Event triggers.

Conditions​

Optionally, add conditions to control when the template triggers:

  • Each condition is defined by field, operator, and value.
  • You can choose:
    • Match All – all conditions must be true (AND logic), or
    • Match Any – at least one condition must be true (OR logic).

Topic​

Each template has a topic that identifies where its events are published for the Streaming API.

  • The topic name is generated by the system based on your environment and the selected event.
  • The topic is shown in the template form; you do not create or manage it separately.
  • This topic name is the logical identifier used by Streaming API clients when creating subscriptions.

Internal infrastructure and physical topic details are managed by Mambu and are intentionally abstracted from customer configuration.

Contents (payload)​

The template body defines the payload that will be sent to your consumers when the event is published.

You can:

  • Structure the payload (for example, as JSON).
  • Use placeholders to inject values from the triggering context (such as client, account, or payment order data).

The Streaming API delivers your payload together with metadata such as event identifiers and timestamps.

For more details on placeholders, see Placeholders.

Subscriptions and delivery​

There are two levels of subscription:

  1. Template subscriptions (Opt-in / Opt-out).
  2. Streaming API subscriptions (for your client applications).

Template subscriptions (Notification Requests)​

Template subscriptions control whether events are produced for a given recipient.

  • Streaming templates follow the same subscription model as other channels.
  • Recipients must be subscribed for events to be generated for them:
    • Opt-in: recipients are only included if they are explicitly subscribed.
    • Opt-out: recipients are auto-subscribed the first time; they can later unsubscribe.
  • You can subscribe or unsubscribe recipients via More > Set Notifications on their profile.

Streaming API subscriptions (client side)​

Your client applications use the Streaming API to subscribe and read events from the topics exposed by your templates.

A typical Streaming API workflow:

  1. Create a subscription

    • Use the Streaming API to create a subscription to one or more streams/topics.
    • The subscription defines what you will read.

  2. Open an event stream

    • Call the Streaming API endpoint that returns a continuous stream of events for the subscription.
    • Keep this connection open while processing events.

  3. Process events and commit cursors

    • As you process events, commit the cursor to record the position you have read up to.
    • If you reconnect later, you can resume from the committed cursor.

  4. Delete the subscription

    • When you no longer need the events, delete the subscription to stop producing data for that consumer.

Refer to the API Reference for details on resources such as subscriptions, events, streams, and cursor commits.

Delivery behavior (high-level)​

  • Delivery: At-least-once. Your consumers should be idempotent and able to handle occasional duplicate events.
  • Ordering: Events are ordered for a given stream/partition within a subscription. Do not assume global ordering across different topics or subscriptions.
  • Retention: Events are stored for a limited retention window. If a subscription is idle for longer than that window, older events may no longer be available.

Authentication and access​

Using the Streaming API requires:

  • An API Consumer configured in your tenant.
  • An API key associated with that API Consumer.

Use the API key to authenticate your Streaming API requests, following the guidance in the Streaming API → Authentication section of the API Reference.

Troubleshooting and tips​

  • No events are received

    • Check that the template Status is Active.
    • Verify that the relevant events are actually occurring in your tenant.
    • Confirm that recipients are subscribed (Opt-in) or were auto-subscribed (Opt-out).
    • Ensure your Streaming API subscription is created against the correct topic and is in an active state.

  • Unexpected duplicates

    • Design your consumers to be idempotent (for example, by tracking event IDs) to handle at-least-once delivery.

  • Authorization errors

    • Verify that the correct API Consumer and API key are used.
    • Check that your API Consumer is allowed to access the Streaming API.

Operational details such as underlying broker technology, partitions, and internal metrics are managed by Mambu and are intentionally not exposed in this documentation.