Webhooks allow Dash to send HTTP requests to a third-party web server, alerting that server of events occurring within Dash. Typically, events would be fired for new calls, when a call is answered, and when a call is finished, though other events will be added in the future.

Webhook Types

The following Webhooks are available on all Dash accounts:

Channel Answer
Channel Bridge
Channel Create
Channel Destroy
Call Parking
Notifications Webhook
- New Voicemail Message
- Voicemail Box Full
- Successful Fax Transmission
- Fax Transmission Error
- Fax Reception Error
- Missed Call
- Device Registration
- Device De-Registration

Webhook Schema

Webhooks are subscriptions to allowed events that, when the event occurs, the event data is sent to the URI set in the Webhook document.

Key	Description	Type	Default	Required
`custom_data`	These properties will be added to the event and will overwrite existing values.	`object()`		`false`
`enabled`	Is the webhook enabled and running	`boolean()`	`true`	`false`
`hook`	The trigger event for a request being made to 'callback_uri'.	`string()`		`true`
`http_verb`	What HTTP method to use when contacting the server	`string('get'	'post')`	`post`
`name`	A friendly name for the webhook	`string()`		`true`
`retries`	Retry the request this many times (if it fails)	`integer()`	`2`	`false`
`uri`	The 3rd party URI to call out to an event	`string()`		`true`

Webook Payload

Here's what you can expect to receive when a webhook fires to your server:

Base Payload

hook_event: The type of hook being fired
call_direction: "inbound" or "outbound", relative to Dash
timestamp: gregorian timestamp of the event
account_id: ID of the account generating the event
request: SIP Request
to: SIP To
from: SIP From
call_id: SIP Call ID
other_leg_call_id: If bridged, the Call-ID of the other leg
caller_id_name: Caller ID Name
caller_id_number: Caller ID Number
callee_id_name: Callee Name
callee_id_number: Callee Number

Most of these fields should be present on all payloads.

Hook Specific

channel_create
- hook_event: channel_create
channel_answer
- hook_event: channel_answer
channel_destroy
- hook_event: channel_destroy
- hangup_cause: SIP Hangup Cause (NORMAL_CLEARING, ORIGINATOR_CANCEL, etc)
- hangup_code: SIP Hangup Code (404, 503, etc)

Payloads for Creating Webhooks

Missed Calls Webhook

{
   "data":{
      "name":"Missed Call",
      "hook":"notifications",
      "include_subaccounts":false,
      "http_verb":"get",
      "retries":4,
      "uri":"<https://hooks.zapier.com/hooks/catch/591668/xlwslm/>",
      "type":"account",
      "action":"doc_created",
      "custom_data":{
         "type":"missed_call"
      },
      "enabled":true,
      "include_internal_legs":true,
      "id":"51840ffc8bde832a1f5477def32cd665"
   }
}

New Voicemail Mail Message Webhook

{
   "data":{
      "name":"Missed Call",
      "hook":"notifications",
      "include_subaccounts":false,
      "http_verb":"get",
      "retries":4,
      "uri":"<https://hooks.zapier.com/hooks/catch/591668/xlwslm/>",
      "type":"account",
      "action":"doc_created",
      "custom_data":{
         "type":"missed_call"
      },
      "enabled":true,
      "include_internal_legs":true,
      "id":"51840ffc8bde832a1f5477def32cd665"
   }
}

Create Webhook

Creates a webhook using parameters passed in the payload.

API

Method: PUT

<https://public-api.virtualpbx.com:8443/v2/accounts/{{account_id}>}/webhooks

Payload

{
  "data": {
    "name": "My New Webhook",
    "uri": "<http://my.server.net>",
    "http_verb": "post",
    "hook": "channel_destroy",
    "retries": 4
  }
}

List Webhooks

List all webhooks on the account. Any webhooks with disable_reason, in summary, have been auto-disabled.

API

Method: GET

<https://public-api.virtualpbx.com:8443/v2/accounts/{{account_id}>}/webhooks

Payload

{
  "data": {
    "name": "Main Blacklist",
    "numbers": {
      "+14154846048": {}
    }
  }
}

Edit Webhook

Edit a webhook with any changes passed in the payload.

API

Method: POST

<https://public-api.virtualpbx.com:8443/v2/accounts/{{account_id}>}/webhooks/{{webhook_id}}

Payload

{
  "data": {
    "enabled": true,
  "retiees": 4
  }
}

Delete Webhook

Delete a webhook. This is permanent and unrecoverable.

API

Method: DELETE

<https://public-api.virtualpbx.com:8443/v2/accounts/{{account_id}>}/webhooks/{{webhook_id}}