Skip to content

Webhooks and Websockets#

About Myself#

  1. About Myself

    • James Aimonetti
    • Kazoo Architect and Community at 2600Hz
    • mc_ on freenode
  2. Presenter


Webhooks - High level#

  • Request events to be sent to your server
  • Read-only
  • AMQP->HTTP bridge
  • Custom webhooks via callflows


  • Simple HTTP request is sent from Kazoo to your server
    • Respond with 200 only (auto-disabled otherwise)
    • If possible, relay data to separate process for use
  • Update rows in a database or spreadsheet
  • Screen pops
  • Use with Pivot to build reactive routing logic

Available Webhooks#

  • Code can be found here
  • Channel events
    • CREATE
    • ANSWER
    • BRIDGE
  • Inbound/outbound faxes

Available Webhooks (cont)#

  • Parked calls
  • Account objects
    • Accounts, callflows, devices, fax boxes, media (MOH, IVR, voicemails), users, voicemail boxes, faxes
    • Created/edited/deleted
    • Billing systems
  • Custom webhooks from callflows
    • Analytics on IVRs

Query for webhooks available#

curl -v -X GET http://{SERVER}:8000/v2/webhooks

Creating a webhook#

curl -v -X PUT \
-H "X-Auth-Token: {AUTH_TOKEN}" \
-H "Content-Type: application/json" \
-d '{"data": {
    "name": "New Calls",
    "uri": "http://{YOUR_SERVER}/calls/new.php",
    "http_verb": "post",
    "hook": "channel_create",
}}' \

Webhook Request#

  • GET: query string parameters
  • POST: x-www-urlencoded-form body
  • Data sent will be the AMQP JSON payload, encoded for the HTTP method chosen
  • No processing of the response (except HTTP response code)

The future of webhooks#

  • Reseller hooks for all sub-accounts
    • Added Oct 6
    • Create one hook, receive events for all sub-accounts
  • Feature requests welcome!


  • Persistent connection
  • Lower overhead (no polling)
  • Get events and issue commands to Kazoo
  • Richer UI interactions with Kazoo (operator console)

Anatomy of websocket connection#

![img](./images/WebSockets-Diagram.png "![img](//")

Create a websocket connection#

  • Ensure blackhole application is running
  • Open a connection

Subscribe for events#

Subscribe for an account's new calls#

Subscribe for multiple types of events#

Subscribe for doc change events#

Unsubscribe from events#

Monster makes this easy#

Monster makes this easy (cont)#

Query for available bindings#

curl -v -X GET http://{CROSSBAR}:8000/v2/websockets | python -mjson.tool
    "data": {
        "call": [
                "binding": "call.CHANNEL_CREATE.*",
                "event": "CHANNEL_CREATE"
                "binding": "call.CHANNEL_ANSWER.*",
                "event": "CHANNEL_ANSWER"
                "binding": "call.CHANNEL_DESTROY.*",
                "event": "CHANNEL_DESTROY"
                "binding": "call.CHANNEL_BRIDGE.*",
                "event": "CHANNEL_BRIDGE"

Event categories available#

  • Channel events
  • Fax events
  • Objects - identical to webhooks

Fetch account's socket connections#

curl -v -X GET \
-H "X-Auth-Token: {AUTH_TOKEN}" \
    "data": [
    "status": "success"

Fetch bindings for a socket ID#

curl -v -X GET \
-H "X-Auth-Token: {AUTH_TOKEN}" \
    "data": [
            "account_id": "{ACCOUNT_ID}",
            "auth_token": "{AUTH_TOKEN}",
            "bindings": [
            "websocket_session_id": "{SOCKET_ID}"
    "status": "success"

Execute commands#

curl -v -X PUT \
    -H "Content-Type: application/json" \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -d '{"data": {"action": "metaflow", "data": { "module", "hangup" }}' \

The future#

  • Support sending commands
    • Currently, cb_channels is the way (via metaflows/konami)
    • Pivot over websockets (great idea from yesterday!)
  • More events exposed for building richer UIs
    • Conference events
    • Notifications (vm left, system alerts)

Thank You#