{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml","oas-openapi/api.yaml":"oas-openapi/api.yaml"},"props":{"metadata":{"markdoc":{"tagList":["openapi-code-sample"]},"type":"markdown"},"seo":{"title":"Real-time events (WebSocket)","description":"Fondo is the ground breaking open finance platform that lets you focus on what matters","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":["openapi"],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"real-time-events-websocket","__idx":0},"children":["Real-time events (WebSocket)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Partners can open a WebSocket connection to receive real-time events for a specific client — for example when an order is placed, a transaction settles, or a journey completes."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"connection","__idx":1},"children":["Connection"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Open a WebSocket to:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Sandbox"]}," – ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["wss://api.sandbox.fondo.se/v2/partner/client/{clientId}/subscribe"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["NPC"]}," – ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["wss://api.npc.fondo.se/v2/partner/client/{clientId}/subscribe"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Production"]}," – ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["wss://api.fondo.se/v2/partner/client/{clientId}/subscribe"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["wss://"]}," scheme — TLS is required."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["On success the server sends a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hello"]}," event:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{ \"eventType\": \"hello\" }\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"authentication","__idx":2},"children":["Authentication"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Authenticate the WebSocket handshake with the same OAuth2 bearer token used for REST requests, sent as an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization: Bearer <token>"]}," header on the upgrade request:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"GET /v2/partner/client/{clientId}/subscribe HTTP/1.1\nHost: api.sandbox.fondo.se\nUpgrade: websocket\nConnection: Upgrade\nSec-WebSocket-Version: 13\nSec-WebSocket-Key: <client-generated nonce>\nAuthorization: Bearer <YOUR_TOKEN_HERE>\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The token is checked once at handshake time. The connection then stays open until either side closes it — it is not severed when the token's session TTL expires, so you do not need to reconnect on token refresh."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Browsers cannot set the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization"]}," header on the WebSocket handshake. Connect from a backend."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If your partner account uses IP allowlisting, the source IP of the WebSocket handshake must also be on the allowlist; otherwise the upgrade is rejected with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"common-errors","__idx":3},"children":["Common errors"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"You see"},"children":["You see"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Cause"},"children":["Cause"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404 Not Found"]}," on a plain ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The endpoint only responds to a WebSocket handshake. Sending a normal ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET"]}," (curl, Postman, browser navigation, the API Reference \"Try it\" button) returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404"]},". Use a WebSocket client."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}," on the upgrade"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Missing or malformed ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization"]}," header."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}," on the upgrade"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Token is invalid, expired, or doesn't belong to a session. Re-fetch a token via ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/api-guide/getting-started/authentication"},"children":["Authentication"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]}," on the upgrade"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The token's partner does not own ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["clientId"]},", or your source IP is not allowlisted."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"heartbeat","__idx":4},"children":["Heartbeat"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The server sends a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["heartbeat"]}," event roughly every five seconds to keep the connection alive:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{ \"eventType\": \"heartbeat\" }\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"event-structure","__idx":5},"children":["Event structure"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every event is a JSON object with an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["eventType"]}," field. Events that carry data also include a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payload"]}," object:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".create"]}]}," events contain ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payload.current"]}," — the created resource."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".update"]}]}," events contain ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payload.current"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payload.previous"]}," — the resource before and after the change."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".delete"]}]}," events contain ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payload.previous"]}," — the resource that was removed."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"eventType\": \"order.create\",\n  \"payload\": {\n    \"current\": { \"id\": \"abc123\", \"status\": \"pending\", \"…\": \"…\" }\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"event-types","__idx":6},"children":["Event types"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Event type"},"children":["Event type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Trigger"},"children":["Trigger"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["account.create"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Account created"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["account.update"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Account updated"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["account.delete"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Account deleted"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client.update"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Client updated"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client.delete"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Client deleted"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["order.create"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Order created"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["order.update"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Order updated"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["order.delete"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Order canceled"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cashTransaction.create"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Cash transaction created"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cashTransaction.update"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Cash transaction updated"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cashTransaction.delete"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Cash transaction deleted"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fundTransaction.create"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Fund transaction created"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fundTransaction.update"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Fund transaction updated"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fundTransaction.delete"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Fund transaction deleted"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["journey.update"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Journey updated"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["journey.delete"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Journey deleted"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["instrument.reloaded"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Fund data refreshed for all instruments"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"scoping","__idx":7},"children":["Scoping"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each connection receives events for the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["clientId"]}," in the URL only. The exception is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["instrument.reloaded"]},", which is broadcast to all connections."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"reconnection","__idx":8},"children":["Reconnection"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The server may close the connection at any time (for example during a deployment) with close code ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["1001"]},". Clients should implement reconnection with exponential back-off."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There is no event replay or sequence numbering. Any state you missed during the disconnect must be reconciled via the REST API — for example by re-fetching orders modified since your last known timestamp. Treat the WebSocket as a low-latency notifier, not as a durable event log."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"examples","__idx":9},"children":["Examples"]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-openapi/api.yaml","operationId":"getWebsocket","parameters":{},"environments":{}},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/api/subscription/getwebsocket"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["getWebsocket"]}," operation"]}," in the API Reference for the full event schema and response codes."]}]},"headings":[{"value":"Real-time events (WebSocket)","id":"real-time-events-websocket","depth":1},{"value":"Connection","id":"connection","depth":2},{"value":"Authentication","id":"authentication","depth":2},{"value":"Common errors","id":"common-errors","depth":2},{"value":"Heartbeat","id":"heartbeat","depth":2},{"value":"Event structure","id":"event-structure","depth":2},{"value":"Event types","id":"event-types","depth":2},{"value":"Scoping","id":"scoping","depth":2},{"value":"Reconnection","id":"reconnection","depth":2},{"value":"Examples","id":"examples","depth":2}],"frontmatter":{"seo":{"title":"Real-time events (WebSocket)"}},"lastModified":"2026-04-29T07:39:00.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/api-guide/subscriptions","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}