Event Streaming API
  • 13 Jul 2020
  • 3 Minutes To Read
  • Print
  • Share
  • Dark
    Light

Event Streaming API

  • Print
  • Share
  • Dark
    Light

Early Access feature
If you would like to learn more about this feature or want to request early-access, please get in touch with your Mambu Customer Success Manager to discuss your requirements.
Pre-requisites
In order to make use of this feature you must have enabled and set up API consumers

The purpose of the Events Streaming API is to provide high-performance and a reliable mechanism for streaming significant amounts of data out of Mambu on a constant basis, without posing unnecessary pressure on API and WebHooks infrastructure.

This document covers set up in the Mambu UI, for API documentation please see here.

How to use Events Streaming

1. Create Events Streaming Notifications

To create new Events Streaming notifications go to: AdministrationEvents Streaming and click the Add Notification button.

add a new event streaming api destination

2. Event Stream Notification Store Form

In order to make use of the Event Stream notification, we introduced a new concept, named Topic. The Topic value represents the name of the channel to which Mambu notifications are submitted, is based on the selected notification event type and is auto-generated. Notifications can be streamed through Event Streaming API, using the topic value.

create a new notification for the event streaming api

3. Subscribe & Consume Events Streaming API

In order to subscribe to Mambu notifications events and consume them, a dedicated API is exposed.

Preconditions:
An Api Key should be generated for Streaming API. For more details please see section Events Streaming API Authentication.

The typical workflow is:

  1. Create a Subscription specifying the event types you want to read. The event type value is represented by the Topic value in the store notification template form. The consumer should be able to subscribe to one or multiple topics.

    Single event type:

    POST: https://[tenantID].[env].mambucloud.com/api/v1/subscriptions

    {
        "owning_application": "streaming-api-",
        "event_types": ["mrn.event.testapp.streamingapi.savings_deposit"]
    }
    
    Response: Status: 200 OK
    {
        "owning_application": "streaming-api-",
        "event_types": ["mrn.event.testapp.streamingapi.savings_deposit"
        ],
        "consumer_group": "default",
        "read_from": "end",
        "initial_cursors": [],
        "authorization": null,
        "id": "[subscriptionID]",
        "created_at": "2019-03-05T09:59:30.057Z",
        "updated_at": "2019-03-05T09:59:30.057Z"
    }
    

    Multiple event types (single subscription ID is generated for the event types):

    POST: https://[tenantID].[env].mambucloud.com/api/v1/subscriptions

    {
        "owning_application": "streaming-api-",
        "event_types": ["mrn.event.testapp.streamingapi.savings_deposit",                        "mrn.event.testapp.streamingapi.client_rejected"]
    }
    
    Response: Status: 200 OK
    {
        "owning_application": "streaming-api-",
        "event_types": [
            "mrn.event.testapp.streamingapi.client_rejected",
            "mrn.event.testapp.streamingapi.savings_deposit"
        ],
        "consumer_group": "default",
        "read_from": "end",
        "initial_cursors": [],
        "authorization": null,
        "id": "[subscriptionID]",
        "created_at": "2019-03-11T11:32:19.107Z",
        "updated_at": "2019-03-11T11:32:19.107Z"
    }
    
  2. Start reading batches of events from the subscription

    • Trigger at least one event for the event topic defined under AdministrationEvents Streaming
    • Read the event from the server console by using the above command
    curl -v 'https://[tenantID.environment]/api/v1/subscriptions/[subscriptionID]/events' \
    -H 'apikey: [streamingApi_apiKey]'
    
    • All the events that are under the same subscription ID and were triggered ( Events Stream communication type is Sent) are listed.
    {
      "cursor": {
        "event_type": "mrn.event.testapp.streamingapi.savings_deposit",
        "cursor_token": "[cursorToken]",
        "offset": "001-0001-000000000000000002",
        "partition": "1"
      },
      "events": [
        {
          "metadata": {
            "eid": "5119bd1b-973f-44ae-8d2d-314169619282",
            "occurred_at": "2019-03-11T13:30:30.497Z",
            "content_type": "text/plain; charset=UTF-8",
            "category": "DATA",
            "event_type": "mrn.event.testapp.streamingapi.savings_deposit"
          },
          "template_name": "group-deposit",
          "body": ""
        }
      ]
    }
    
  3. Commit the cursors found in the event batches back to Mambu, which will store the offsets.

Preconditions: in order to be able to commit the cursor after Step 2 is executed the generated ID is passed as a request header with the name X-Mambu-StreamId.

X-Mambu-StreamId: [fieldValue]

Request headers for accessing the streaming api

POST: https://[tenantID].[env].mambucloud.com/api/v1/subscriptions/[subscriptionID]/cursors?apikey

{
    "items": [
        {
            "event_type": "mrn.event.testapp.streamingapi.savings_deposit",
            "cursor_token": "[cursorToken]",
            "offset": "001-0001-000000000000000001",
            "partition": "1"
        }
    ]
}

Note: once a subscription is read and the cursor is committed it is no longer displayed in the logs. The cursor should be committed in max 60 seconds, otherwise the POST operation should be re-done.


Ask the Mambu Community

If you have a question about how anything works or have come across something you haven't seen explained here, get in touch with our community of fellow users and Mambuvians where someone will lend a hand.

Ask a question about Event Streaming APIs

* If you don't already have an account you will be prompted to create one when you first visit the site.

Was This Article Helpful?