Creates a subscription that delivers transactions to you in real time. Each subscription supports two delivery modes — you can use one or both:
Webhook (push delivery)
Set webhookUrl to your HTTPS endpoint. The system will POST each update to your URL as it occurs. Deliveries are retried with exponential backoff (1m, 5m, 30m, 2h, 12h) for up to 5 attempts. Each delivery includes an X-Noves-Signature header containing an HMAC-SHA256 hex digest of the request body, computed with the secret returned when you create the subscription. Use this to verify that payloads are authentic.
WebSocket (pull delivery)
Set websocketEnabled to true. The response will include a websocketUrl you can connect to. The generated URL includes the subscription secret; clients should use that URL as-is. In practice the connection URL is wss://.../streams/{id}/ws?secret=.... Updates are pushed to all connected clients in real time. If no client is connected, messages are queued for up to 1 hour and replayed automatically when a client reconnects.
Filters
Use the filters object to control which updates are delivered. It contains three categories of filters (OR'd — a match in any category delivers the update):
partyFilter (top-level) — Only deliver updates involving this Canton party address. Each filter category applies the party check in its own way.
filters.txTypeFilters
Match by classification type. Pass an array of one or more values:
| Category | Types |
|---|---|
| Transfers | transfer, mergeSplit, unlock, failedTransfer |
| Rewards | validatorRewards, appRewards, svRewards |
| Fees | fee |
| Traffic | buyTraffic |
| Coupons | issueCoupon, redeemCoupon, convertToCoupon |
| Subscriptions | paySubscription |
| Preapprovals | createTransferPreapproval, acceptTransferPreapproval, createAndAcceptTransferPreapproval |
| Activity | createActivityMarker |
| Token ops | mintToken |
| Admin | createValidatorLicense, provisionWallet, createFeaturedAppRight |
| Other | unclassified |
filters.rawEventFilters
Required when the filters object is supplied. Pass an empty array when unused.
Match by the presence of specific raw DAML events. Each entry specifies a template
module (required), entity (optional), and event type: "created", "archived", or omit for any.
Example: [{ "templateModule": "Splice.Amulet", "templateEntity": "Amulet", "eventType": "created" }]
filters.utilityFilters
Required when the filters object is supplied. Pass an empty array when unused. Composite filters that inspect the transaction payload. Supported values:
allCCMovements— matches any transaction where Canton Coin moves for the party (checksclassificationData.transfersfor CC token transfers where the party is sender or receiver). Invalid filter values are rejected with HTTP 400.
Raw data
Set includeRawData to true to receive the original unprocessed transaction alongside the classified data. When enabled, each message includes a rawData field with the full raw payload.
Payload format
Each delivered message (webhook POST body or WebSocket message) is a JSON object:
{ "subscriptionId": "uuid", "updateId": "...", "effectiveAt": "ISO-8601", "timestamp": "ISO-8601", "data": { /* classified transaction */ }, "rawData": { /* optional, if includeRawData is true */ } }
The data field contains the full classified transaction with parties, values, and transaction data.