Webhook API

Webhooks enable the HostedPBX to send HTTP requests to a third-party webserver, alerting that server of events that occur within HostedPBX. Currently, events are triggered for new calls, when a call is answered, and when a call is finished.

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

API calls

Click on each call to view the endpoint, method, and request example.

Parameters

The table shows the possible parameters available for webhook requests.

Key Description Type Options/Min/Max/Default
hook Required The trigger event for a request being made to 'callback_uri'. string
name Required. A friendly name for the webhook. string
uri Required. The 3rd party URI to call out to an event. string
custom_data These properties are added to the event and overwrite existing values. object
enabled Indicates if the webhook is enabled and running. boolean The default is true.
http_verb Indicates which Method and endpoint to use when contacting the server. string get, post. The default is post.
include_subaccounts Specifies if the webhook should be fired for subaccount events. boolean
retries Indicates how many times the request should be retried (if it fails). integer The default is 2.

Get webhooks

Returns installed webhooks. Webhooks are installed by the system administrator; you can query Crossbar to see which are installed. Some webhooks also include parameters specific to that webhook that can be used to modify the behaviour of the webhook.

Method and endpoint

  GET /v2/webhooks

Request

  curl -v -X GET \
      -H "Content-Type:application/json" \
      -H "X-Auth-Token: {AUTH_TOKEN} \
      https://apps.hostedpbx.ie:8443/v2/webhooks

Response

  {
      "auth_token": "{AUTH_TOKEN}",
      "data": [
          {
              "description": "Events when calls end",
              "id": "channel_destroy",
              "name": "channel_destroy"
          },
          {
              "description": "Events when new calls start",
              "id": "channel_create",
              "name": "channel_create"
          },
          {
              "description": "Events for when the channel is answered by the endpoint",
              "id": "channel_answer",
              "name": "channel_answer"
          },
          {
             "description": "Receive notifications when objects in HostedPBX are changed",
             "id": "object",
             "modifiers": {
                 "action": {
                     "description": "A list of object actions to handle",
                     "items": [
                         "doc_created",
                         "doc_edited",
                         "doc_deleted"
                     ],
                     "type": "array"
                 },
                 "type": {
                     "description": "A list of object types to handle",
                     "items": [
                         "account",
                         "callflow",
                         "device",
                         "faxbox",
                         "media",
                         "user",
                         "vmbox"
                     ],
                     "type": "array"
                 },
                 "types": {
                     "description": "A list of object types to handle",
                     "items": {
                         "type": "string"
                     },
                     "type": "array"
                 }
             },
             "name": "object"
         }
     ],
     "page_size": 4,
     "request_id": "{REQUEST_ID}",
     "revision": "{REVISION}",
     "status": "success"
  }

Get available webhooks

Returns a list of available webhooks.

Method and endpoint

  GET /v2/accounts/{ACCOUNT_ID}/webhooks

NOTE: Any webhooks with disable_reason in the summary has been auto-disabled.

Request

  curl -v -X GET \
      -H "X-Auth-Token: {AUTH_TOKEN}" \
      https://apps.hostedpbx.ie:8443/v2/accounts/{ACCOUNT_ID}/webhooks

Create a webhook

This request creates a webhook.

Method and endpoint

  PUT /v2/accounts/{ACCOUNT_ID}/webhooks

Request

  curl -v -X PUT \
      -H "X-Auth-Token: {AUTH_TOKEN}" \
      -H "Content-Type: application/json" \
      -d '{"data": {
          "name": "New Calls",
          "uri": "http://my.{SERVER}/calls/new.php",
          "http_verb": "post",
          "hook": "channel_create",
          "retries":3
      }}' \
      https://apps.hostedpbx.ie:8443/v2/accounts/{ACCOUNT_ID}/webhooks

Get webhook

Returns details of a specific webhook.

Method and endpoint

  GET /v2/accounts/{ACCOUNT_ID}/webhooks/{WEBHOOK_ID}

Request

  curl -v -X GET \
      -H "X-Auth-Token: {AUTH_TOKEN}" \
      https://apps.hostedpbx.ie:8443/v2/accounts/{ACCOUNT_ID}/webhooks/{WEBHOOK_ID}

Edit webhook

Modifies a specific webhook.

Method and endpoint

  POST /v2/accounts/{ACCOUNT_ID}/webhooks/{WEBHOOK_ID}

Request

  curl -v -X POST \
      -H "X-Auth-Token: {AUTH_TOKEN}" \
      -H "Content-Type: application/json" \
      -d '{"data": {
          "name": "New Calls",
          "uri": "http://my.{SERVER}/calls/new_calls.php",
          "http_verb": "post",
          "hook": "channel_create",
          "retries": 3
      }}' \
      https://apps.hostedpbx.ie:8443/v2/accounts/{ACCOUNT_ID}/webhooks/{WEBHOOK_ID}

Patch webhook

Partially updates a webhook.

Method and endpoint

  PATCH /v2/accounts/{ACCOUNT_ID}/webhooks/{WEBHOOK_ID}

You can also patch an existing webhook.

Request

curl -v -X PATCH \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H "Content-Type: application/json" \
    -d '{"data":{"enabled":true}}' \
    https://apps.hostedpbx.ie:8443/v2/accounts/{ACCOUNT_ID}/webhooks/{WEBHOOK_ID}

Delete a webhook

Deletes a webhook.

Method and endpoint

  DELETE /v2/accounts/{ACCOUNT_ID}/webhooks/{WEBHOOK_ID}

Request

  curl -v -X DELETE \
      -H "X-Auth-Token: {AUTH_TOKEN}" \
      https://apps.hostedpbx.ie:8443/v2/accounts/{ACCOUNT_ID}/webhooks/{WEBHOOK_ID}

Get webhook attempts

Returns a list of recent attempts. You can use this query for troubleshooting because Webhooks tracks all attempts to send the hook payloads to your URIs.

Method and endpoint

  GET /v2/accounts/{ACCOUNT_ID}/webhooks/attempts

Request

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    https://apps.hostedpbx.ie:8443/v2/accounts/{ACCOUNT_ID}/webhooks/attempts

Response

{
    "auth_token": "{AUTH_TOKEN}",
    "data": [
        {
            "client_error": "nxdomain",
            "hook_id": "{HOOK_ID}",
            "reason": "hostedpbx http client error",
            "result": "failure",
            "retries left": 2,
            "timestamp": 63590996563
        },
        {
            "hook_id": "{HOOK_ID}",
            "result": "success",
            "timestamp": 63590996562
        }
    ],
    "page_size": 2,
    "request_id": "{REQUEST_ID}",
    "status": "success"

    }

Get details for a specific attempt

Returns details of a specific attempt.

Method and endpoint

  GET /v2/accounts/{ACCOUNT_ID}/webhooks/{WEBHOOK_ID}/attempts

Request

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    https://apps.hostedpbx.ie:8443/v2/accounts/{ACCOUNT_ID}/webhooks/{WEBHOOK_ID}/attempts

Re-enable auto-disabled hooks in bulk

Bulk action to re-enable webhooks on account and descendants. Webhooks auto-disables failing hooks if, for instance, HostedPBX can't reach your server, or if you take too long to respond with 200 OK. If you are a reseller with webhooks in your client accounts, it can be difficult go through all your accounts and re-enable each hook.

Enable account hooks

Enables the webhooks on an account.

Method and endpoint

  PATCH /v2/accounts/{ACCOUNT_ID}/webhooks

Request

curl -v -X PATCH \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -d '{"data":{"re-enable":true}}' \
    https://apps.hostedpbx.ie:8443/v2/accounts/{ACCOUNT_ID}/webhooks

Enable account and descendant account hooks

Enables the account and sub-accounts hooks.

Method and endpoint

  PATCH /v2/accounts/{ACCOUNT_ID}/descendants/webhooks

Request

curl -v -X PATCH \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -d '{"data":{"re-enable":true}}' \
    https://apps.hostedpbx.ie:8443/v2/accounts/{ACCOUNT_ID}/descendants/webhooks

Base parameters

The following parameters are returned when a webhook makes requests to your server:

Field Description
hook_event The type of hook being fired.
call_direction The direction of the call inbound or outbound, relative to HostedPBX.
timestamp A gregorian timestamp of the event.
account_id The ID of the account generating the event.
request The SIP request.
to The SIP "to".
from The SIP "from".
call_id The SIP call ID.
other_leg_call_id If bridged, the call ID of the other leg.
caller_id_name The caller ID name.
caller_id_number The caller ID number.
callee_id_name The callee name.
callee_id_number The callee number.

NOTE: Most of these fields should be present on all payloads.

Hook-specific parameters

The following parameters are present on specific hooks.

Event Field Description
channel_create hook_event A channel_createhook event.
channel_answer hook_event A channel_answerhook event.
channel_destroy hook_event A channel_destroyhook event.
channel_destroy hangup_cause The SIP hangup cause (NORMAL_CLEARING, ORIGINATOR_CANCEL, and so on)
channel_destroy hangup_code The SIP hangup code (404, 503, and so on)
doc hook_event A doc hook event.
doc action A doc action doc_created, doc_updated, doc_deleted.
doc type A doc type user, vmbox, callflow, account, device, faxbox, media.

Hook-specific custom data

To restrict the kind of document or the action or both, you can set the custom data to:

  {
     "type": "user",
     "action": "doc_edited"
  }