Skip to content

Webhooks

Webhooks are triggered by Call Event, such as call ringing, call answered, call hangup etc. When that event occurs, VoIPstudio platform makes an HTTPS (POST) request to the URL configured for the Webhook - a third party web server (API). See more more on Wikipedia

webhooks-config.png

Figure 9.1 Enabling and Configuring Webhooks.
  1. Click on Integrations.
  2. Scroll down to Webshooks and Enable.
  3. Select Add Webhook to create a new one.
  4. Enter any name for the new Webhook to indentify.
  5. Select events to listen for. Note Call State change type include all events.
  6. Enter the URL used by your application.
  7. To Edit any Webhooks simply click on the name.
  8. If no longer needed simply click disable Webhooks.

NOTE: Only HTTPS Protocol is supported.

NOTE: For URL to be saved it need to be valid and reply to https requests.

Available events

With VoIPtudio WebHooks we monitor following call status events categories:

  • Call Missed
  • Call Ringing
  • Call Connected
  • Call Ended
  • Call State Change - this last one include all previous event types. It is triggered for any call state change: INITIAL, RINING, CONNECTED, ON_HOLD, HANGUP.

Note monitored events show call status and they are matching SIP signalling messages as detailed bellow:

  • INITIAL: SIP INVITE send to the corresponding endpoint (Phone).
  • RINGING: endpoint reply from SIP INVITE. It is indicating that the endpoint is active and it is already ringing.
  • CONNECTED: SIP 200 message indicating that user answered the call.
  • ON_HOLD: The call has ben paused. This corresponds to SIP INVITE with body: a=sendonly
  • HANGUP: indicating that call has ended. This corresponds to SIP BYE Message.

Apart from call status events, the following additional events are available:

  • SMS Received

Event attributes

Events are delivered as HTTPs POST requests with JSON body - for example:

{
"id":"uk003.608920d55f7ac3.77053295",
"event_time":"2021-04-28 08:46:13",
"event_name":"call.hangup",
"call_id":139543232,
"state":"HANGUP",
"connected_at":"2021-04-28 08:46:02",
"start_time":"2021-04-28 08:45:55",
"context":"LOCAL_USER",
"destination":"in",
"duration":11,
"t_cause":"Normal Clearing",
"src":"447854740947",
"src_id":"0",
"src_name":"\"442035141598\" <2035141598>",
"dst":"441183211001",
"dst_id":"10002",
"dst_name":"John Smith"
}

Call status event attributes are as follows:

  • id (string) - unique ID of an Event
  • event_time (string) - time of an Event in Y-m-d H:i:s format UTC timezone
  • event_name (string) - name of an Event, one of:
    • call.initial - Call in initial state
    • call.ringing - Call is ringing
    • call.missed - Missed (unanswered) call
    • call.connected - Call is connected
    • call.hangup - Call is terminated
    • call.hold - Call is put onhold
    • call.unhold - Call is unhold
  • call_id (integer) - this is numeric ID of the call. It can be later used to access resources via REST API. The relation to REST API resources is:
    • call.id - example REST API request:
    • cdr.live_id - example REST API request: GET /v1.1/cdrs?filter=[{"property":"live_id","operator":"=","value":"{call.id}"}]
    • monitor.live_id - example REST API request: GET /v1.1/monitors?filter=[{"property":"live_id","operator":"=","value":"{call.id}"}]
  • state (string) - state of the Call, one of:
    • INITIAL - Initial call state
    • ACCEPTED - Click 2 call has been accepted
    • RINGING - Destination is rining
    • CONNECTED - Call is connected
    • ON_HOLD - Call is on hold
    • HANGUP - Call is terminated
  • connected_at (string) - time when call was connected in Y-m-d H:i:s format UTC timezone. Default null
  • start_time (string) - time when call started in Y-m-d H:i:s format UTC timezone.
  • context (string) - context of the call within PBX system
  • destination (string) - in for inbound call, out for outbound call
  • duration (integer) - duration of the call is seconds
  • t_cause (string) - Termination Cause
  • src (string) - Number of the call source
  • src_id (integer) - Numeric ID of call source
  • src_name (string) - Name of the call source
  • dst (string) - Number of the call destination
  • dst_id (integer) - Numeric ID of call destination
  • dst_name (string) - Name of the call destination

SMS Received event attributes are as follows:

  • id (string) - unique ID of an Event
  • event_time (string) - time of an Event in Y-m-d H:i:s format UTC timezone
  • event_name (string) - name of an Event sms.received
  • customer_id (integer) - Numeric ID of Customer Account which received SMS message
  • user_id (integer) - Numeric ID of User Account which received SMS message (optional, default: null)
  • from_no (string) - originating phone number
  • to_no (string) - phone number which received SMS message
  • text (string) - body of received message

After receiving Webhook event as in example above (call_id = 139543232), one can retrieve and update Call resource via REST API:

GET /v1.1/calls/139543232

and to Transfer the call to extension 2002:

PATCH /v1.1/calls/139543232
{
"dst": "2002"
}

Note: /calls REST API resource represents active ongoing call. Once call is terminated and Event call.hangup received it is no longer available at /calls endpoint. Instead it can be accessed at /cdrs (Call Details Report) and /monitors (Call Recordings) endpoints using filter on live_id attribute with value of call_id from Webhook event, for example:

GET /v1.1/cdrs?filter=[{"property":"live_id","operator":"=","value":"139543232"}]

or

GET /v1.1/monitors?filter=[{"property":"live_id","operator":"=","value":"139543232"}]

Troubleshooting Webhooks

Call detailed Reports from VoIPstudio dashboard allow customers to monitor all SIP packets workflow in a graphical view for every single call. It also display the Webhooks notifications send to your listening URL, including their content. This might be very useful to troubleshoot your Webhooks notification deployment.

You only need to browse Call Detailed Report and click on corresponding calls and check for the submitted events and their content. This should match the notification you received on server. Please follow steps bellow:

webhooks-troubleshooting.png

Figure 9.2 Troubleshooting Webhooks.
  1. From Admin dashboard panel open History section.
  2. Click CDR, this will open list with recent calls processed under VoIPstudio platform.
  3. Identify and click the call you would like to inspect to open detailed info of the corresponding call.
  4. Under call flow identify your API server column.
  5. You must see one POST request send to the server for each event you ave Webhook event set. Click on it to expand.
  6. Details of the Webhook post reply are shown here.