WebSocket

wss://<host>/v1/ws?key=idc_live_...

A single connection carries notifications for all three chains. You choose what to receive on it by sending subscribe messages after the handshake, not by opening separate sockets per chain.

Connecting

const ws = new WebSocket("wss://<host>/v1/ws?key=idc_live_...");

The key travels as a ?key= query parameter here, not as an Authorization header. That is specific to this endpoint: every other call in this API uses the header. See Authentication for why the WebSocket handshake cannot carry a header and falls back to the query string.

Subscribing

Once the socket is open, send a subscribe message:

{ "action": "subscribe", "chain": "eid", "event": "credential.revoked" }

A socket can carry multiple subscriptions: send another subscribe message to add another chain/event pair. Any message whose action is not subscribe is silently ignored.

chain accepts a wildcard, event does not

chain accepts eid, ethr, fabric, or * for all three. event has no equivalent wildcard: it must match one of the exact event names below. This is asymmetric on purpose, not an oversight, so do not assume a wildcard works on both fields. A subscription's chain is treated as a match when it's * or equal to the event's chain; its event is only ever treated as a match when it's equal, with no * case at all.

Event frame

A matching event arrives as:

{ "chain": "ethr", "event": "attestation.pushed", "data": { "...": "..." } }

data varies by event and is not covered by this page beyond the events table below.

Events

attestation.pushed is currently emitted for Ethereum only. It does not yet fire for Hyperledger Fabric pushes, so a subscription for {"chain": "fabric", "event": "attestation.pushed"} will not receive anything today.

Where events come from

These notifications come from Attestra's own chain watchers, the same processes that track eIDChain, Ethereum and Fabric for changes. They do not come from the oracle, and nothing in an event frame is signed.

Treat a socket event as a notification that something happened, not as proof of it. If you need a result a chain can verify, call Verify and check the signed attestation it returns.

Keepalive

The server pings every 30 seconds. A browser WebSocket answers pongs automatically, so no action is needed there. In Node or any non-browser client, confirm your WebSocket library replies to pings itself; if it doesn't, the server will eventually treat the connection as dead. Write timeout per frame is 5 seconds.

Backpressure

Publishing to subscribers never blocks. If a subscriber's buffer is full when an event is published, that subscriber misses the event rather than the server stalling to wait for it, and other subscribers are unaffected.

Each subscription has a buffer of 64 slots, and each connection additionally has a 128-slot fan-in channel shared across all of that connection's subscriptions. Once either fills, further events for that subscription or connection are dropped rather than queued indefinitely.

This makes the delivery guarantee on this endpoint deliberately weak: a slow consumer loses events silently. If your integration cannot afford to miss a credential.revoked notification, do not rely on this socket for it. Use Webhooks instead: deliveries are durable, written to storage before the first delivery attempt, and retried on failure.