You can be notified when events take place within Enswitch, such as calls starting, being routed, being answered, or ending, and text messages being received or sent. More event types are expected to be added in future. These events are sent to a URL of your choice via HTTP/HTTPS POST. To enable this, set the URL in the "Send events to URL" setting on the Settings » Customer page on the Enswitch web interface. 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 Enswitch 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.
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.
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.