Page tree
Skip to end of metadata
Go to start of metadata


WebHooks currently provide a way to hook 3rd-party applications up to Kazoo to receive events related to the account. From a low-level perspective, WebHooks acts as an AMQP->HTTP bridge for certain white-listed call events. Want to know when a new call starts on an account? What a notification when Josh receives a call, Dhruvi answers a call, or Jean Roch hangs up? Configure the appropriate webhooks with your URL and Kazoo will send the URL an HTTP request with the relevant information!


See the most recent documentation here.


Currently Supported WebHooks

  • New channel (what most think of as a new call)
  • Answered channel (the called party has answered)
  • Hungup channel (the call is hungup)


As of v3.07 the hook names have changed to "channel_create", "channel_answer", and "channel_destroy" for consistency. Check the schema if you are unsure what your version is using. Also, "custom_data" is only supported on v3.07+.

If the REST requests below fail with a 400 because of schema validation errors, make sure to run the following SUP command:


$> sup whapps_maintenance refresh system_schemas
This should refresh all the system schema JSON documents, including the new webhooks.json


  • GET /accounts/{account_id}/webhooks
    • Listing of current webhooks
    • Sample cURL request:

      curl -X GET -H "X-Auth-Token: 12345abcde"{account_id}/webhooks
  • PUT /accounts/{account_id}/webhooks
    • Creates a new webhook
    • See the schema for fields to send
    • Sample cURL request:

      curl -X PUT -H "X-Auth-Token: 12345abcde" -H "Content-Type: application/json"{account_id}/webhooks \
        -d '{"data":{"name":"New Calls", "uri":"", "http_verb":"post", "hook":"channel_create", "retries":3}}
  • GET /accounts/{account_id}/webhooks/{webhook_id}
    • See the details of a webhook
    • Sample cURL request:

      curl -X GET -H "X-Auth-Token: 12345abcde"{account_id}/webhooks/{webhook_id}
  • POST /accounts/{account_id}/webhooks/{webhook_id}
    • Edit the particulars of a webhook
    • Sample cURL request:

      curl -X POST -H "X-Auth-Token: 12345abcde" -H "Content-Type: application/json"{account_id}/webhooks{webhook_id} \
        -d '{"data":{"name":"New Calls", "uri":"", "http_verb":"post", "hook":"channel_create", "retries":3}}
  • DELETE /accounts/{account_id}/webhooks/{webhook_id}
    • Delete a webhook
    • Sample cURL request:

      curl -X DELETE -H "X-Auth-Token: 12345abcde"{account_id}/webhooks/{webhook_id}
  • GET /accounts/{account_id}/webhooks/attempts
    • Get a list of recent attempts to your server (maybe useful in debugging)
    • Sample cURL request:

      curl -X GET -H "X-Auth-Token: 12345abcde"{account_id}/webhooks/attempts
  • GET /accounts/{account_id}/webhooks/{webhook_id}/attempts
    • Get a list of recent attempts to this webhook
    • Sample cURL request:

      curl -X GET -H "X-Auth-Token: 12345abcde"{account_id}/webhooks/{webhook_id}/attempts


If you need to add additional (static) data to the event payload you can do so by adding a "custom_data" object to the webhook.  Note: if you use a conflicting property name, such as "account_id", you will overwrite the event property.  For example:

url -X PUT -H "X-Auth-Token: 12345abcde" -H "Content-Type: application/json"{account_id}/webhooks \
  -d '{"data":{"name":"New Calls", "uri":"", "http_verb":"post", "hook":"channel_create", "retries":3, \
       "custom_data": {"account_id": "my_crm_account_id", "screen_pop": true}}}'


Will result in the following event:

call_direction: inbound
timestamp: 63557035175
account_id: my_crm_account_id
request: *
to: *
call_id: 1545197196@
hook_event: channel_create
screen_pop: true




  • No labels


  1. CSB

    The PUT example is inconsistent with the schema:



    hook is not described in the schema.


             "description":"The trigger event for a request being made to 'callback_uri'.",
    I guess the schema needs to be updated?
    1. You are right, and yet you are wrong (smile)

      The link to the schema points to the version on master, which is, at this point, out of date. The new Webhooks code is brewing on the KAZOO-1003 branch in a pull request, which has the updated schema for how webhooks should be working. So, hopefully the pull request is accepted today or tomorrow, at which point the schema link will point to the correct schema doc.

      Sorry for the confusion!