# WebSocket Subscriptions

Listen for events on your Realm so your integration can automatically trigger reactions. Orangepill uses Websocket to notify your application when an event occures in your Realm. WebSockets are particularly useful for asynchronous events like when a new account is created, new transaction is processed or when incoming deposits are receieved.

## Events

<table><thead><tr><th width="287.5">Event</th><th width="433.5">Description</th></tr></thead><tbody><tr><td><code>user.created</code></td><td>New user is successfully created.</td></tr><tr><td><code>user.updated</code></td><td>User is updated.</td></tr><tr><td><code>user.deleted</code></td><td>User is deleted. All related content is cascade deleted: identities, virtual currencies, accounts, transactions, deposits, withdrawals.</td></tr><tr><td><code>identity.created</code></td><td>New identity is successfully created.</td></tr><tr><td><code>identity.updated</code></td><td>Identity is updated.</td></tr><tr><td><code>identity.</code>deleted</td><td>Identity is deleted.</td></tr><tr><td><code>persons.sync.started*</code></td><td>Two-way synchronization of persons started.</td></tr><tr><td><code>persons.sync.done*</code></td><td>Two-way synchronization succesfully finished.</td></tr><tr><td><code>person.created*</code></td><td>Person profile is created.</td></tr><tr><td><code>person.updated*</code></td><td>Person profile is updated.</td></tr><tr><td><code>person.deleted*</code></td><td>Person profile is deleted.</td></tr><tr><td><code>person.assigned*</code></td><td>Person is assigned to Identity.</td></tr><tr><td><code>person.unassigned*</code></td><td>Person is unassigned from Identity.</td></tr><tr><td><code>company.created*</code></td><td>Company profile is created.</td></tr><tr><td><code>company.updated*</code></td><td>Company profile is updated.</td></tr><tr><td><code>company.deleted*</code></td><td>Company profile is deleted.</td></tr><tr><td><code>CHANNEL.message.sent*</code></td><td>Message is sent to CHANNEL. CHANNEL is sms, whatsapp, html and any other enabled.</td></tr><tr><td><code>CHANNEL.message.failed*</code></td><td>Message failed to CHANNEL. CHANNEL is sms, whatsapp, html and any other enabled.</td></tr><tr><td><code>account.creating</code></td><td>New account is being created.</td></tr><tr><td><code>account.created</code></td><td>Account is successfully created. </td></tr><tr><td><code>account.failed</code></td><td>Account creation has failed.</td></tr><tr><td><code>account.updated</code></td><td>Account has been updated.</td></tr><tr><td><code>account.incoming</code></td><td>Incoming balance.</td></tr><tr><td><code>account.outgoing</code></td><td>Outgoing balance.</td></tr><tr><td><code>transaction.processing</code></td><td>New transaction is created and being processed.</td></tr><tr><td><code>transaction.updated</code></td><td>Transaction is updated.</td></tr><tr><td><code>transaction.done</code></td><td>Transaction is successfully processed. </td></tr><tr><td><code>transaction.failed</code></td><td>Transaction processing failed.</td></tr><tr><td><code>deposit.pending</code></td><td>Incoming deposit detected.</td></tr><tr><td><code>deposit.received</code></td><td>Incoming deposit received.</td></tr><tr><td><code>deposit.processing</code></td><td>Deposit is stored and processing.</td></tr><tr><td><code>deposit.gas</code></td><td>Gas is withdrawn for ERC20, BEP20, TRC20 deposit processing.</td></tr><tr><td><code>deposit.processed</code></td><td>Deposit is successfully processed. </td></tr><tr><td><code>deposit.failed</code></td><td>Deposit processing failed.</td></tr><tr><td><code>withdrawal.creating</code></td><td>New withdrawal is created and being processed.</td></tr><tr><td><code>withdrawal.processed</code></td><td>Withdrawal is successfully processed. </td></tr><tr><td><code>withdrawal.failed</code></td><td>Withdrawal processing failed.</td></tr><tr><td><code>currency.created</code></td><td>Virtual currency is successfully created.</td></tr><tr><td><code>currency.failed</code></td><td>Virtual currency failed creating.</td></tr><tr><td><code>currency.issued</code></td><td>New Virtual currency supply issued. </td></tr><tr><td><code>currency.destroyed</code></td><td>Virtual currency supply destroyed.</td></tr><tr><td><code>alias.created</code></td><td>Alias successfully created.</td></tr><tr><td><code>alias.updated</code></td><td>Alias successfully updated.</td></tr><tr><td><code>alias.deleted</code></td><td>Alias successfully deleted.</td></tr><tr><td>apps.<code>forward.done</code></td><td>Transaction was successfully forwarded.</td></tr><tr><td>apps.<code>forward.failed</code></td><td>Transaction forwarding failed.</td></tr><tr><td><code>apps.payment.pending</code></td><td>Apps.Payment is created and pending.</td></tr><tr><td><code>apps.payment.status</code></td><td>Apps.Payment status change.</td></tr><tr><td><code>apps.payment.processing</code></td><td>Apps.Payment is being processed.</td></tr><tr><td><code>apps.payment.done</code></td><td>Apps.Payment is successfully processed.</td></tr><tr><td><code>apps.payment.failed</code></td><td>Apps.Payment processing failed.</td></tr><tr><td><code>apps.deposit.pending</code></td><td>Apps.Deposit is created and pending.</td></tr><tr><td><code>apps.deposit.processing</code></td><td>Apps.Deposit is being processed.</td></tr><tr><td><code>apps.deposit.done</code></td><td>Apps.Deposit is succesfully processed.</td></tr><tr><td><code>apps.deposit.failed</code></td><td>Apps.Deposit processing failed.</td></tr><tr><td><code>kycs.session.created</code></td><td>KYC session created</td></tr><tr><td><code>kycs.session.status.updated</code></td><td>KYC session status updated</td></tr></tbody></table>

{% hint style="info" %}
Events marked with \* supported with Infobip extension enabled.
{% endhint %}

## Event data

Each notification will include name of the event and id of the entity affected by event. If details of event are of your interest, use information from event `data` to retrieve entity details.

```json
{
    "type": "notification", // event notification
    "event": "transaction.processed", // event name
    "data": "63967141191e9023f356df9f", // id of affected entity
    "timestamp": "162553625262" // Date.now()
}
```

Connect to WebSocket notification server using URL `wss://stream.orangepill.cloud`.

To **subscribe** for notification events use your Realm Key in message.

```json
{ "type": "subscribe", "realm": <YOUR_REALM_KEY> }
```

You can **unsubscribe** from receiving notification events using similar message.

```json
{ "type": "unsubscribe", "realm": <YOUR_REALM_KEY> }
```

In successful response to subscribe and unsubscribe events you will receive object.

```json
{ "type":"info", "realm":"c9d4744c-0eae-4457-a665-2c18b9ac132b", "timestamp": 1671547687 }
```

If subscribe is not successful you will receive info and error objects.

```json
{ "type":"info", "realm":"NONE", "timestamp": 1671547687 }
```

```json
{ "type":"error", "realm":"Invalid Realm Key.", "timestamp": 1671547687 } }
```

Subscribe event response.

```json
{ "type":"subscribe", "realm":"c9d4744c-0eae-4457-a665-2c18b9ac132b", "timestamp": 1671547687 } }
```

Unsubscribe event response.

```json
{ "type":"unsubscribe", "realm":"c9d4744c-0eae-4457-a665-2c18b9ac132b", "timestamp": 1671547687 } }
```

## Example using JavaScript

Use <https://api.orangepill.cloud> for live example of Event Stream Explorer.

```javascript
// JavaScript example

const ws = new Sockette('wss://stream.orangepill.cloud', {
  timeout: 5e3,
  maxAttempts: 10,
  onopen: e => subscribe(),
  onmessage: e => message(e),
  onreconnect: e => {console.log('Reconnecting...'); subscribe();},
  onmaximum: e => {console.log('Stop Attempting!')},
  onclose: e => {console.log('Closed!'); cancelKeepAlive();},
  onerror: e => {console.log('Error:')}
});


function message(message) {

    var notification = JSON.parse(message.data);
    
    var event = notification.data.event;
    var data = notification.data.data;
    var timestamp = notification.data.timestamp;      

    // handle event with your logic
    switch (event) {
        case "account.created":
            // your logic here
        break;
        // ....
    }
}

function subscribe() {

    const realm = "<YOUR_REALM_KEY>";
    const obj = { "type": "subscribe", "realm": realm }
    ws.send(JSON.stringify(obj));
    keepAlive();

}

function unsubscribe() { 

    const realm = "<YOUR_REALM_KEY>";
    const obj = { "type": "unsubscribe", "realm": realm }
    ws.send(JSON.stringify(obj));
    
}

let timerId = 0; 

function keepAlive(timeout = 10000) { 
    ws.send('PING');  
    timerId = setTimeout(keepAlive, timeout);  
}

function cancelKeepAlive() {  
    if (timerId) {  
        clearTimeout(timerId);  
    }  
}

```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.orangepill.cloud/websocket-subscriptions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.