Saltar a contenido

Webhooks

Los Webhooks se generan en base a los eventos de llamada ocurridos en el sistema. Tales como llamada en timbre, llamada respondida, llamada terminada, etz. Cuando estos eventos pasan, la plataforma de VoIPstudio hace una petición HTTPS (POST) a la URL configurada para el Webhook - Una API de un tercero. Vea mas en Wikipedia

webhooks-config.png

Figura 9.1 Habilitar y Configurar Webhooks.
  1. Haga clic en Integraciones.
  2. Descienda hasta Webshooks y habilite la integración.
  3. Seleccione Añadir Webhook para crear uno.
  4. Introduzca el Nombre para el nuevo Webhook de tal manera que lo pueda identificar.
  5. Seleccione los eventos a los que tiene que reacionar. Tenga en cuenta que la categoria Cambio de Estado en la llamada incluye todos los eventos.
  6. Introduzca la URL de su aplicación.
  7. Para modificar un Webhooks existente solo haga click en el nombre.
  8. Si no los necesita puede desactivar los Webhooks.

NOTE: Los webhooks solo funcionan en HTTPS.

NOTE: Para que la URL se guarde tiene que ser válida y responder a peticiones HTTPS. (el servicio tiene que estar levantado)

Eventos Disponibles

En VoIPstudio puede monitorizar las siguientes categorías de eventos:

  • Llamada perdida
  • Llamada en timbre
  • Llamada conectada
  • Llamada terminada
  • Cambio en el estado de la llamada - Incluye todos los eventos anteriores. Reacciona a los sigueintes cambios de estado: INITIAL, RINING, CONNECTED, ON_HOLD, HANGUP.

Tenga en uenta que los eventos monitorizados muestran los cambios en los estados de la llamada en base a la señalización SIP tal como se muestra:

  • 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.

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

The 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

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

Figura 9.2 Troubleshooting Webhooks.
  1. Desde el panel de Administrador abrir la sección de Historial.
  2. Haga clic en CDR, se mostraran todas las llamadas que ha procesado VoIPstudio.
  3. Localice y haga click en la llamada para obtener los detalles.
  4. En la tabla de flujo de paquetes localice la columna correspondiente a su servidor.
  5. Deben aparecer las peticiones POST remitidas a su servidor. Haga clic para expandir.
  6. Los detalles del POST generado en el Webhook aparecerán.