Event Subscriptions

V2 Changes Overview

While not new to v2 event subscriptions received some improvements with v2 most notability the ability to have a subscription be more resilient and support redundancy with the subscription capable of moving between servers if needed for failures. In v2 you can also see status of the subscriptions, counters of posts sent and errors as well as set (or change) a preferred server for the events to be sent from. There is also improved logging and statistics available using iNSight pro including active subscription counts as well as error counters per subscription.

Getting Started with Subscriptions

To begin receiving events, you will need to have a publicly accessible web address or a locally connectable one that our servers can access. Ideally, it should be open from any of the clustered servers to avoid connection issues in failover scenarios. We highly recommend securing the server using HTTPS, but if you are connecting locally or over a secure network, HTTP can also be used. Both protocols support custom ports. This URL will be used as the endpoint for posting data and will be referred to as the "post-url."

Next, you should determine the type of data you are looking to receive. These "models" are documented on the following page and will dictate the nature of the data and the timing of its delivery. It's important to note that some data streams may have high volume, so ensure your system is prepared to handle the data before configuring the URL.

You will also need to specify the scope of the data you want and the associated resources (resellers, domains, and users). Access permissions should align with the desired scope; for example, setting the domain to "*" would typically require reseller or super user permissions.

Consider whether you want to enable geo support. In general, opting for "yes," which is the new v2 default, is recommended unless you intend to subscribe to multiple servers and manage deduplication independently.

All data posts will be transmitted in JSON format, organized as an "array" of "objects." The structure of these objects will be specific to the chosen model.

If you require any further assistance or clarification, please feel free to ask.

This create process is further documented via the api reference page at Create Event Subscription

Available Models

Model	Description
agent	This model will send an even every time a agent entry changes. This will show availability changes in for the agent as well as the queue changes that happen for the agent. Both user and device based agents will be shown.
auditlog	This model will stream 1 per entry in the audit log after they are recorded. This model should be used with super user scoped only. For domain filtering it will be the "target_domain" being filtered.
auditlog_lite	This model is a streamlined version of auditlog model, with the focus on creates and deletes of just a few key objects often used for billing. The objects include domain, user, reseller, and callqueue, agent, conference and phonenumber. Note: phonenumber will only be sent on changes from api (v1 or v2) and not from admin ui changes.
call	This is a model that will send all active call information for all the call events that match the domain and user of the filters. This mean one event for every change to the call including creation, updates and removal. Look for "remove: yes" as for when the call object is being removed.
call_origid	This is a model that is similar to "call" but it is key'd off of changes to the orig_callid only. This means that you will not get as much data including things that happen on the term side of the call like events for multiple users being rung and transfers.
cdr	This model will send you 1 event at the completion of the call. This is usefull if you need to know when calls are complete to trigger up follow up work or go review other needed information like transcriptions, call recordings, etc...
message	This model will send 1 event per message received for chat or sms. Should be used in conjunction with user and domain to limit to single user.
messagesession	This model will send 1 event per session being updated. This could include a new message event or a mark of the session being read.
subscriber	This model will update each time a subscriber is updated and will include most of the fields for a user.
presence	This model is similar to "subscriber" but it will be a more limited dataset being posted focusing on simply user, names, status and presence changes.
voicemail	This model will send 1 event per voicemail being recorded for a user. There is some built in delay so the transcription should be available, but not guaranteed based on vendor latencies. If transcriptions are need your application should queue up a API call to read the voicemail again if needed.

Redundancy

TThe new logic begins by synchronizing the status of all nsnode applications, which is utilized by the API to transmit data. This synchronization ensures that all servers are aware of which applications are running and stable, as well as identifies any servers that may be offline. To assume control of a subscription, a server must demonstrate stability for a continuous period of 60 seconds and have the fewest active subscriptions. In cases of tie-breakers, predefined random information is used, ensuring each server has a predictable next-fail option. Additionally, a new field has been introduced in the v2 dataset, allowing for the designation of a preferred server and the ability to view the current server.

Authenticating and Validating Posts

In certain scenarios, it may be necessary to safeguard your web application against undesirable data. The simplest approach is to restrict incoming traffic solely to the known IP addresses within the cluster. Moreover, starting with V2, a new header called X-Correlation-ID will be introduced, containing the subscription ID. By ensuring the confidentiality of this value, you can employ it to validate incoming posts. In cases where multiple subscriptions target the same URL, this header can also be used for matching purposes.