Monitoring events

You can be notified when events take place within the Enswitch cluster, such as calls starting, being routed, being answered, or ending, text messages being received or sent, SIP registrations, and sipd monitoring the health of Asterisk machines. More event types are expected to be added in future. This reports the same events as the per-customer events but for all customers on the system, plus system-level events not associated with any customer.

There are two ways to do this:

1. HTTP POST

You can configure Enswitch to send events to a URL of your choice via HTTP/HTTPS POST. To enable this, set the URL in the "Send events to URL" setting under Global » Settings » Configuration. One request will be made for each event, passing the fields of the event as fields in the POST body. Each HTTP/HTTPS request will be made directly from the machine on which the event occurs. The response from the URL is ignored, so returning an empty document with Content-Type text/plain is sufficient.

It's important that you secure this URL from third parties sending bogus events, either by restricting access to only the IP addresses of the Enswitch machines, or by passing an authentication key as a URL parameter. It's also important that the URL reply quickly, as routing of calls is delayed until it responds.

2. Websocket

Alternatively, you can connect to a websocket at http://«address»:4875/events/websocket/?authkey=«key» where «address» is the IP address used to connect to messaged and «key» is the messaged authentication key. The values for these can be determined from the "Message daemon IP address" and Message daemon authentication key" settings under Global » Settings » Configuration. You must also enable the "Send events to messaged" setting to tell Enswitch daemons to send events to messaged. Once connected to the websocket, you will receive a websocket frame for each event, with the event fields JSON encoded. For debugging purposes, wscat can be used to monitor the events. For example:

wscat --connect 'http://localhost:4875/events/websocket/?authkey=abcdefghijklmnopqrstuvwxyz123456

which should show events in JSON, such as:

{"asteriskid":"1234567890.1","callid":"1234567890.100000","class":"call","event":"start","machine":1,"timestamp":"1234567890.123456","uniqueid":"1234567890.100000"}

If connecting from outside the Enswitch cluster, it may be necessary to open TCP port 4875 in your iptables or other firewall configuration on the machine or machines running messaged.

Event fields

Both methods send the same set of fields. The particular fields sent depend on the event, with events of the same class and event always sending the same fields. All events include the following fields:

class: The object the event is for. 'call' for events relating to calls, 'message' for events relating to text messages, and so on.
event: The particular event. For example, the start of a call will produce a 'start' event.
timestamp: The Unix timestamp of the event, to the nearest microsecond.

Compatibility

The code on the web server which reads the events must be tolerant of new events, and new fields for existing events, being added without warning even in the middle of stable versions of Enswitch. Code should silently discard any events or fields that it doesn't know how to handle.