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.

• Get webhooks
• Get available webhooks
• Create a webhook
• Get webhook
• Edit webhook
• Patch webhook
• Delete a webhook
• Get webhook attempts
• Get details for a webhook attempt
• Re-enable auto-disables hooks in bulk
• Enable account hooks
• Enable account and descendant account hooks

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"
  }