Skip to main content

Consuming Events from a Subscription

GET /api/subscriptions/{subscription-id}/events

Request​

Events can be consumed by sending a GET request to the subscription's event resource /api/subscriptions/{subscription-id}/events.

Query parameters (batch_limit, batch_flush_timeout, commit_timeout, and others) are unchanged from V1 — see Event Streaming Configurations. Note that max_uncommitted_events is not supported in V2.

note

The consumption of events is handled by your client application. If your client application is not able to process the format of the streaming notification, you may encounter a validation error.

Sample Request

curl -v -X GET "https://TENANT_NAME.mambu.com/api/subscriptions/0691160a-b519-4595-b85c-a400fc73e963/events" \
  -H "Accept: application/vnd.mambu.v2+json"

Response​

The response is a stream that groups events into JSON batches separated by an endline (\n) character, same as V1.

note

When a stream is started, the client receives a header named X-Mambu-StreamId, which must be used when committing cursors. This is unchanged from V1 — see Committing Cursors.

Batches now support multiple event types​

In V1, batches were homogeneous (all events shared one event type). In V2, cursor.event_type is always MIXED — to identify each event's type, use events[].metadata.event_type, which is unchanged.

Sample Response

{
  "cursor": {
    "partition": "shardId-000000000000",
    "offset": "49673591198887640830612221074728717584752617270261317634",
    "event_type": "MIXED",
    "cursor_token": "3b0123a1-532e-4dd3-81ec-aa71a2dd443f"
  },
  "events": [
    {
      "metadata": {
        "eid": "de45b84d-0684-485e-841e-2ab384931f46",
        "occurred_at": "2026-04-15T06:19:58.589Z",
        "content_type": "application/json",
        "category": "DATA",
        "event_type": "mrn.event.TENANT_NAME.streamingapi.savings_deposit"
      },
      "body": {
        "account_id": "GUPO179",
        "account_name": "product1",
        "client_id": "967244213",
        "transaction_id": "186714413",
        "amount": "100.00",
        "datetime": "2026-04-15 06:19:58"
      },
      "template_name": "deposit transaction 3"
    },
    {
      "metadata": {
        "eid": "6acfa3fd-ebb2-44f4-bd85-0aae42579242",
        "occurred_at": "2026-04-15T06:19:58.619Z",
        "content_type": "application/json",
        "category": "DATA",
        "event_type": "mrn.event.TENANT_NAME.streamingapi.savings_created"
      },
      "body": {
        "date": "2026-04-15T06:19:58.1958-03:00",
        "accountId": "GUPO180",
        "creationDate": "2026-04-15T06:19:58.1958-03:00",
        "valueDate": "2026-04-15T06:19:58.1958-03:00",
        "currencyCode": "USD"
      },
      "template_name": "deposit transaction 2"
    }
  ]
}

eid is now a TSID, not a UUID​

metadata.eid changes from a UUID (e.g. fde622d5-f975-4786-8e1d-d328c29761f9) to a shorter, time-sortable TSID (e.g. 0R4ZANE59TB94). Treat it as an opaque string — do not parse, validate its format, or assume a fixed length. This does not affect the X-Mambu-StreamId header, which remains a UUID. See Differences Between Streaming API V1 and V2 for full migration guidance.

Event size limit​

A maximum event size limit has been introduced (default 10 KB, up to 10 MB). When breached, a new error field on the event's metadata carries the details:

"error": {
  "code": "MAX_MESSAGE_SIZE_LIMIT_EXCEEDED",
  "reason": "Event size 368 bytes exceeds of 10 bytes for event 4028c0819d903d2c019d903d90b100ce",
  "location": "communications/messages/4028c0819d903d2c019d903d90b100ce"
}
Last updated on