WebHooks API

Description

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

Currently Supported WebHooks

Call-related:

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

REST API

  • GET /accounts/{account_id}/webhooks
    • Listing of current webhooks
    • Sample cURL request:
curl -X GET -H "X-Auth-Token: 12345abcde" https://www.wirecloud.de/api/v1/accounts/{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" https://www.wirecloud.de/api/v1/accounts/{account_id}/webhooks \
-d '{"data":{"name":"New Calls", "uri":"http://my.server.com/calls/new.php", "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" https://www.wirecloud.de/api/v1/accounts/{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" https://www.wirecloud.de/api/v1/accounts/{account_id}/webhooks{webhook_id} \
-d '{"data":{"name":"New Calls", "uri":"http://my.server.com/calls/new_call.php", "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" https://www.wirecloud.de/api/v1/accounts/{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" https://www.wirecloud.de/api/v1/accounts/{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" https://www.wirecloud.de/api/v1/accounts/{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:

curl -X PUT -H "X-Auth-Token: 12345abcde" -H "Content-Type: application/json" https://www.wirecloud.de/api/v1/accounts/{account_id}/webhooks \
-d '{"data":{"name":"New Calls", "uri":"http://my.server.com/calls/new.php", "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: *97@www.wirecloud.de

to: *97@www.wirecloud.de

from: user_37ccch@www.wirecloud.de

call_id: 4922199999936@88.99.77.55

hook_event: channel_create

screen_pop: true