Webhooks

Los webhooks son una extensión de una API, pero en lugar de que tu código solicite datos a nuestra plataforma API, es Vonage quien te envía los datos. Los datos llegan en forma de solicitud web a tu aplicación. Un webhook puede ser el resultado de una llamada a la API anterior (este tipo de webhook también se denomina «callback»), como una solicitud asíncrona a la Number Insight API. Los webhooks también se utilizan para notificar a tu aplicación eventos como una llamada entrante o un mensaje.

Como los servidores de Vonage deben poder enviar datos a tu aplicación a través de webhooks, debes configurar un servidor web para recibir las solicitudes HTTP entrantes. También debes especificar la URL de cada webhook en tu servidor web para que se puedan enviar datos a cada uno.

Flujo de trabajo de los webhooks

Con los webhooks, es importante que la URL a la que se envían los webhooks esté configurada. Cuando hay datos disponibles, Vonage envía el webhook a tu aplicación como una solicitud HTTP. Tu aplicación debería responder con un código de éxito HTTP para indicar que recibió correctamente los datos.

El proceso es más o menos así:

Los webhooks brindan un mecanismo conveniente para que Vonage envíe información a tu aplicación para eventos como una llamada o mensaje entrante, o un cambio en el estado de la llamada. También pueden usarse para enviar información de seguimiento, como un recibo de entrega que puede estar disponible un tiempo después de la solicitud con la que se relaciona.

¿Qué API admiten webhooks?

La información resultante de las solicitudes enviadas a las API compatibles de Vonage se envía mediante una solicitud HTTP a tu punto final de webhook en un servidor HTTP. Para configurar tu punto final de webhook, visita la Panel de Vonage.

Vonage envía y recupera la siguiente información mediante webhooks:

Configuración de los puntos finales de los webhooks

Los webhooks se utilizan para enviar mensajes entrantes y acuses de recibo.

Mensajes entrantes

Para configurar el webhook utilizado para los mensajes entrantes, vaya a la sección Tus Numbers sección del panel de control de Vonage. Haz clic en «editar» junto al número virtual y configura el URL de devolución de llamada.

También puede utilizar la función CLI de Vonage para establecer el punto final de los mensajes entrantes para un número individual.

Recibos de entrega

Véase el Recibos de entrega guía que figura en la documentación de SMS.

La API avanzada de Number Insight permite enviar los resultados de una búsqueda de números de forma sincrónica o asincrónica.

Fije el callback argumento con la URL de un webhook para recibir la consulta de forma asíncrona.

Véase Number Insight Advanced Async Para más información.

En el caso de las solicitudes de la Voice API, los webhooks se pueden configurar a nivel de aplicación, al crear una llamada o en las acciones de un NCCO.

Webhooks a nivel de aplicación

Los números de Vonage vinculados a las aplicaciones de Vonage utilizarán el answer_url para recuperar una OCN, y el event_url para enviarle información sobre el estado de la llamada. La dirección fallback_answer_url Se puede configurar de forma opcional. Se utiliza cuando answer_url está fuera de línea o devuelve un código de error HTTP. También se utiliza cuando se espera que un evento entregue una NCCO en event_urlpero event_url está desconectado o devuelve un código de estado HTTP.

Puede configurarlos mediante la función API de la aplicaciónen el cuadro de mando o utilizando el CLI de Vonage herramienta.

Webhooks a nivel de Numbers

Puede establecer un webhook de estado para cada número que adquiera. Esto se utilizará para enviarle eventos relacionados con cada número.

Se pueden configurar en la sección «Numbers» de la Panel de control, a través de la CLI de Vonage o a través del Actualizar un Numbers Llamada a la API (concretamente, la voiceStatusCallback propiedad).

Al realizar una llamada saliente

En realizar una nueva llamada saliente, tienes que configurar el answer_url en la llamada a una URL que contenga un NCCO. Los servidores de Vonage recuperarán el NCCO de este punto final y seguirán sus instrucciones a la hora de gestionar la llamada saliente.

Carga útil de la URL de respuesta

La carga útil del answer_url es:

Parámetro	Descripción
to	El número al que se llama
from	El número desde el que se realiza la llamada
conversation_uuid	El UUID del conversación
uuid	El UUID del pierna

Ejemplo de URL:

Copia

/webhooks/answer?to=447700900000&from=447700900001&conversation_uuid=CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab&uuid=aaaaaaaa-bbbb-cccc-dddd-0123456789cd

Dentro de una NCCO

Dentro de un NCCO, los siguientes tipos de acciones admiten una URL de webhook que se utiliza cuando se ejecuta dicha acción:

• record.eventUrl - establecer el punto final de webhook que recibe información sobre la grabación de una Llamada o Conversación
• conversación.eventUrl - Establece la URL del punto final del webhook al que Vonage realiza una llamada asíncrona cuando una conversación cambia de estado para esta acción de conversación.
• connect.eventUrl - establece la URL del punto final del webhook que Vonage llama de forma asíncrona cuando una conversación cambia de estado para esta acción de conexión
• input.eventUrl - establece la URL del punto final de webhook Vonage envía los dígitos pulsados por el receptor de la llamada
• stream.streamUrl - establecer una matriz de URL que apunte a los puntos finales de webhook que alojan el archivo de audio que se transmitirá a la llamada o conversación

Tiempos de espera de los webhooks

Si no se puede acceder a la URL de respuesta, evento o alternativa durante un determinado periodo de tiempo, o si el tiempo de respuesta supera un límite determinado, Vonage volverá a intentar la solicitud una vez. Los tiempos de espera predeterminados de la plataforma para la conexión y la lectura son los siguientes:

Tipo de webhook	Tiempo de espera de conexión	Tiempo de espera del socket
Respuesta	1 segundo	5 segundos
Evento	1 segundo	10 segundos
Respuesta	1 segundo	5 segundos

Estos valores predeterminados se pueden anular mediante un API de la aplicación llamar o en el Panel de control seleccionando la aplicación y haciendo clic en el botón Editar y desplácese hasta la sección Capacidades / Voz:

Encontrará más información sobre estos tiempos de espera en la sección tiempos de espera de webhook de la API de aplicaciones visión general documentación.

Un Aplicaciones puede recibir eventos RTC a través del Gancho web RTC.

La URL del webhook del evento RTC se configura al crear la aplicación utilizando el idioma que prefieras.

También se puede encontrar más información sobre cómo crear una aplicación con funciones RTC en el Documentación de la API de la aplicación.

Verify envía notificaciones de eventos y resúmenes para informarte de las novedades sobre tus solicitudes de verificación. Si eliges la autenticación silenciosa o WhatsApp Codeless como uno de tus canales de autenticación, deberás recibir estas notificaciones para completar con éxito la solicitud.

La URL a la que se enviarán las retrollamadas puede configurarse en su archivo configuración de la aplicación en el panel de control para desarrolladores. Consulta el Referencia API por ejemplo callbacks.

Las API de Mensajes y Dispatch API admiten dos webhooks: el webhook de estado de los mensajes y el webhook de mensajes entrantes. El estado de los mensajes se recibe a través del webhook de estado de los mensajes, mientras que el mensaje en sí se recibe a través del webhook de mensajes entrantes. La configuración de estos webhooks se describe detalladamente en el tema Configuración de webhooks para las API de Messages y Dispatch API.

Recepción de webhooks

Para interactuar con los webhooks de Vonage:

1. Crea una Account de Vonage.
2. Escribe scripts para manejar la información enviada o solicitada por Vonage. Tu servidor debe responder con un código de estado correcto (cualquier código de estado entre 200 OK y 205 Restablecer contenido) a los mensajes entrantes de Vonage. Cualquier otro código que no sea 2xx Este código hará que los servidores de Vonage vuelvan a intentar realizar la devolución de llamada.
3. Publique sus scripts desplegándolos en un servidor (para desarrollo local, pruebe con Ngrok).
4. Configurar un punto final de webhook en la API que quieras utilizar.
5. Realiza una acción (como enviar un SMS) que active ese webhook.

A continuación, la información sobre tu solicitud se envía a tu punto final de webhook.

Descodificación de webhooks firmados

La firma de webhooks se activa mediante por defecto para las API Messages, Dispatch, Verify y Voice. Proporcionan un método para que tu aplicación verifique que una solicitud proviene de Vonage y que su carga útil no ha sido alterada durante el tránsito. Al recibir una solicitud, el webhook entrante incluirá un token JWT en el encabezado de autorización que está firmado con tu secreto de firma.

NOTA: En las aplicaciones de Voice creadas anteriormente, la opción «Webhooks firmados» está desactivada por defecto. Para activarla manualmente, ve a la configuración de la aplicación en el panel de control, haz clic en el enlace «Mostrar funciones avanzadas» en la sección «Funcionalidad de Voice» y, a continuación, activa la Utilizar webhooks firmados Compruébalo:

También puedes desactivarlo para las nuevas aplicaciones marcando esta casilla (no se recomienda; utilízalo solo en casos excepcionales).

La validación de webhooks firmados proporciona una serie de ventajas de seguridad, entre ellas:

• La capacidad de verificar que una solicitud proviene de Vonage
• Garantizar que el mensaje no haya sido alterado durante su transmisión
• Defensa contra la interceptación y la repetición posterior

Validación de webhooks firmados

La validación de webhooks firmados consta de dos partes:

1. Verify la solicitud
2. Verificación de la carga útil (opcional)

Verify la solicitud

Los webhooks incluirán un JWT en el archivo Authorization encabezado. Utiliza la clave API incluida en las reclamaciones del JWT para identificar cuál de tus secretos de firma se ha utilizado para firmar la solicitud. El secreto utilizado para firmar la solicitud se corresponde con el secreto de firma asociado a la api_key incluido en las reivindicaciones JWT. Puede identificar su secreto de firma en el Panel de control. Se recomienda que los secretos de firma tengan una longitud mínima de 32 bits para garantizar su seguridad.

Verify the payload has not been tampered with in transit

Una vez que hayas comprobado la autenticidad de la solicitud, puedes, si lo deseas, verificar que el contenido de la solicitud no haya sido alterado comparando el hash SHA-256 de dicho contenido con el payload_hash encontrado en las reclamaciones JWT. Si no coinciden, la carga útil ha sido manipulada durante el tránsito. Sólo es necesario verificar la carga útil si se utiliza HTTP en lugar de HTTPS, ya que la seguridad de la capa de transporte (TLS) evita que Ataques MITM.

El ejemplo de código que aparece a continuación muestra cómo verificar la firma de un webhook. Se recomienda utilizar el protocolo HTTPS, ya que garantiza que tanto la solicitud como la respuesta estén cifradas tanto en el lado del cliente como en el del servidor.

npm install @vonage/jwt express

const app = require('express')();
const bodyParser = require('body-parser');

app.use(bodyParser.json());
app.use(bodyParser.urlencoded({
  extended: true,
}));

app
  .route('/webhooks/inbound-message')
  .post(handleInboundMessage);

const handleInboundMessage = (request, response) => {
  const token = request.headers.authorization.split(' ')[1];
  if (verifySignature(token, VONAGE_API_SIGNATURE_SECRET)) {
    console.log('Valid signature');
  } else {
    console.log('Invalid signature');
  }

  response.send(200);
};

app.listen(process.env.PORT || 3000);

composer require vonage/client

require_once __DIR__ . '../../config.php';
require_once __DIR__ . '../../vendor/autoload.php';

$signature = new Vonage\Client\Credentials\SignatureSecret(VONAGE_API_KEY, VONAGE_SIGNATURE_SECRET, 'sha256');
$client = new Vonage\Client($signature);

$message = new Vonage\SMS\Message\SMS(
    TO_NUMBER,
    FROM_NUMBER,
    'This is a signed text'
);

$client->sms()->send($message);

// Incoming Request
$signature = new Vonage\Client\Signature($_GET, VONAGE_SIGNATURE_SECRET, 'sha256');
$isValid = $signature->check($_GET['sig']);

pip install vonage python-dotenv fastapi[standard]

import os
from os.path import dirname, join

from dotenv import load_dotenv

# Load the environment
envpath = join(dirname(__file__), '../.env')
load_dotenv(envpath)


VONAGE_SIGNATURE_SECRET = os.getenv('VONAGE_SIGNATURE_SECRET')

from fastapi import FastAPI, Request
from vonage_jwt.verify_jwt import verify_signature

app = FastAPI()


@app.get('/inbound')
async def verify_signed_webhook(request: Request):
    # Need to get the JWT after "Bearer " in the authorization header
    auth_header = request.headers["authorization"].split()
    token = auth_header[1].strip()

    if verify_signature(token, VONAGE_SIGNATURE_SECRET):
        print('Valid signature')
    else:
        print('Invalid signature')

Ejemplo de JWT firmado

// header
{
  "alg": "HS256",
  "typ": "JWT",
}
// payload
{
  "iat": 1587494962,
  "jti": "c5ba8f24-1a14-4c10-bfdf-3fbe8ce511b5",
  "iss": "Vonage",
  "payload_hash" : "d6c0e74b5857df20e3b7e51b30c0c2a40ec73a77879b6f074ddc7a2317dd031b",
  "api_key": "a1b2c3d",
  "application_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
}

Cabecera JWT firmada

El contenido del encabezado del JWT firmado se describe en la siguiente tabla:

Carga JWT firmada

El contenido de la carga útil JWT firmada se describe en la siguiente tabla, utilizando los valores incluidos en el JWT firmado de ejemplo mostrado anteriormente:

Probar los webhooks de forma local

Para comprobar que los webhooks funcionan correctamente en tu aplicación ejecutada localmente, tendrás que crear un túnel seguro entre Vonage y tu aplicación. Puedes hacerlo con una aplicación de túneles seguros como, por ejemplo, Ngrok. Consulta el Pruebas con Ngrok para más información.

Configurar el cortafuegos

Si restringes el tráfico entrante (incluidos los recibos de entrega), debes agregar las direcciones IP de Vonage a la lista de direcciones IP aprobadas de tu firewall. Puedes encontrar más información sobre cómo hacerlo en nuestra base de conocimientos:

• Rangos de voz IP
• Rangos IP SMS
• Mensajes y rangos IP de envío
• Number Insight Avanzado Async IP Rangos

Consejos para depurar los webhooks

Empieza poco a poco - Publica el script más breve que se te ocurra para responder cuando se reciba el webhook y, si es posible, muestra alguna información de depuración. De este modo, te asegurarás de que la URL es la que crees que es y de que puedes ver la salida o los registros de la aplicación.

Código defensivo - Comprueba que los datos existen y contienen lo que esperabas antes de utilizarlos. Dependiendo de tu configuración, podrías recibir datos inesperados, así que tenlo siempre en cuenta.

Ver ejemplos - Vonage proporciona ejemplos implementados con varias pilas de tecnología en un intento por brindar soporte a tantos desarrolladores como sea posible. Para ver ejemplos de código con webhooks, consulta lo siguiente:

• Recibir un SMS
• Gestionar los albaranes de entrega
• Recibir una llamada entrante

También puedes consultar la sección de fragmentos de código de la documentación de la API que estés utilizando.

Véase también

• Encontrará más información sobre los tipos de webhooks y las funciones de las aplicaciones en la sección Documentación de las aplicaciones.