Webhooks

Los webhooks son una extensión de una API, pero en lugar de que tu código solicite datos de nuestra plataforma API, Vonage te envía los datos a ti. Los datos llegan en una solicitud web a tu aplicación. Un webhook puede ser el resultado de una llamada API anterior (este tipo de webhook también se denomina "devolución de llamada"), como una solicitud asincrónica a Number Insight API. Los webhooks también se utilizan para notificar a su aplicación de 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 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 a las API compatibles de Vonage se envía en una solicitud HTTP a tu punto final de webhook en un servidor HTTP. Para configurar tu punto final de webhook, visita la página Panel de Vonage.

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

Establecer puntos finales de webhook

Los webhooks se utilizan para entregar mensajes entrantes y recibos de entrega.

Mensajes entrantes

Para configurar el webhook utilizado para los mensajes entrantes, vaya a la sección Tus Numbers del panel de Vonage. Haz clic en 'editar' para el 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 en la documentación de SMS.

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 hará que los servidores de Vonage vuelvan a intentar 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 desea utilizar.
5. Realiza una acción (como enviar un SMS) que active ese webhook.

A continuación, la información sobre su solicitud se envía a su punto final 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 voz creadas anteriormente, la opción Webhooks firmados está desactivada por defecto. Para activarlo manualmente, vaya a la configuración de la aplicación en el Panel de control, haga clic en el enlace "Mostrar funciones avanzadas" en la sección Capacidad de voz y, a continuación, active la opción Utilizar webhooks firmados Compruébalo:

También puede desactivarlo para las nuevas aplicaciones mediante esta casilla (no se recomienda, utilícelo sólo 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 ha sido manipulado durante el tránsito.
• 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. Verificación de la solicitud
2. Verificación de la carga útil (opcional)

Verificación de la solicitud

Los webhooks incluirán un JWT en el archivo Authorization header. Utilice la clave API incluida en las reivindicaciones JWT para identificar cuál de sus 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 cabecera api_key incluido en las reivindicaciones JWT. Puede identificar su secreto de firma en el Cuadro de mandos. Se recomienda que los secretos de firma no sean inferiores a 32 bits para garantizar su seguridad.

Verify the payload has not been tampered with in transit

Una vez que haya verificado la autenticidad de la solicitud, puede verificar opcionalmente que la carga útil de la solicitud no ha sido manipulada comparando un hash SHA-256 de la carga útil con el archivo 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 siguiente ejemplo de código muestra cómo verificar la firma de un webhook. Se recomienda utilizar el protocolo HTTPS, ya que garantiza que la solicitud y la respuesta estén cifradas tanto en el cliente como en el 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 de la cabecera JWT firmada 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 localmente

Para probar el correcto funcionamiento de los webhooks en tu aplicación que se ejecuta localmente, necesitarás crear un túnel seguro entre Vonage y tu aplicación. Puedes hacerlo con una aplicación de túnel seguro como Ngrok. Ver 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 webhooks

Empezar poco a poco - Publica el script más pequeño posible que se te ocurra para responder cuando se reciba el webhook y quizás imprimir alguna información de depuración. Así te aseguras 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 puede consultar la sección de fragmentos de código de la documentación de la API que esté utilizando.

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