Crochets Web

Les crochets Web sont une extension d'une API, mais au lieu que votre code demande des données à notre plateforme API, Vonage vous envoie les données. Les données arrivent dans une requête Web à votre application. Un webhook peut être le résultat d'un appel API antérieur (ce type de webhook est également appelé " callback "), comme une demande asynchrone à l'API Number Insight. Les webhooks sont également utilisés pour notifier votre application d'événements tels qu'un appel ou un message entrant.

Étant donné que les serveurs Vonage doivent pouvoir envoyer des données à votre application via les webhooks, vous devez configurer un serveur web pour recevoir les requêtes HTTP entrantes. Vous devez également spécifier l'URL de chaque webhook sur votre serveur web afin que les données puissent être envoyées à chacun d'entre eux.

Flux de travail des webhooks

Avec les webhooks, il est important que l'URL à laquelle envoyer les webhooks soit configurée. Lorsque des données sont disponibles, Vonage envoie le webhook à votre application sous la forme d'une requête HTTP. Votre application doit répondre par un code de réussite HTTP pour indiquer qu'elle a reçu les données avec succès.

Le processus se déroule comme suit :

Les Webhooks constituent un mécanisme pratique permettant à Vonage d'envoyer des informations à votre application pour des événements tels qu'un appel ou un message entrant, ou un changement d'état de l'appel. Ils peuvent également être utilisés pour envoyer des informations de suivi telles qu'un reçu de livraison qui peut être disponible quelque temps après la demande à laquelle il se rapporte.

Quelles sont les API qui prennent en charge les webhooks ?

Les informations résultant des demandes adressées aux API Vonage prises en charge sont envoyées dans une demande HTTP à votre point de terminaison webhook sur un serveur HTTP. Pour configurer votre point de terminaison webhook, veuillez visiter le site Web de Vonage. Tableau de bord Vonage.

Vonage envoie et récupère les informations suivantes à l'aide de webhooks :

Définition des points de terminaison des webhooks

Les webhooks sont utilisés pour délivrer des messages entrants et des accusés de réception.

Messages entrants

Pour configurer le webhook utilisé pour les messages entrants, allez dans la section Vos Numbers du tableau de bord de Vonage. Cliquez sur 'edit' pour le numéro virtuel et définissez le paramètre URL de rappel.

Vous pouvez également utiliser la fonction CLI Vonage pour définir le point de terminaison des messages entrants pour un numéro individuel.

Récépissés de livraison

Voir le Récépissés de livraison dans la documentation du SMS.

Réception de webhooks

Pour interagir avec les webhooks de Vonage :

1. Créez un Account Vonage.
2. Rédigez des scripts pour traiter les informations envoyées ou demandées par Vonage. Votre serveur doit répondre avec un code d'état de succès (tout code d'état entre 200 OK et 205 Reset Content) aux messages entrants de Vonage. Tout autre code que 2xx fera en sorte que les serveurs de Vonage tentent à nouveau de livrer le rappel.
3. Publiez vos scripts en les déployant sur un serveur (pour un développement local, essayez Ngrok).
4. Configurer un point de terminaison webhook dans l'API que vous souhaitez utiliser.
5. Effectuez une action (comme l'envoi d'un SMS) qui déclenchera ce webhook.

Les informations relatives à votre demande sont ensuite envoyées à votre point de terminaison webhook.

Décodage des webhooks signés

La signature des webhooks est activée par par défaut pour les API Messages, Dispatch, Verify et Voice. Elles permettent à votre application de vérifier qu'une demande provient bien de Vonage et que son contenu n'a pas été altéré pendant le transport. Lors de la réception d'une demande, le webhook entrant inclura un jeton JWT dans l'en-tête d'autorisation qui est signé avec votre secret de signature.

NOTE: Pour les applications vocales créées précédemment, Signed Webhooks est désactivé par défaut. Pour l'activer manuellement, allez dans les paramètres de l'application dans le tableau de bord, cliquez sur le lien "Afficher les fonctionnalités avancées" dans la section Capacité vocale, puis activez l'option Utiliser des webhooks signés vérifier :

Vous pouvez également le désactiver pour les nouvelles applications en cochant cette case (non recommandé, à n'utiliser que dans des cas exceptionnels).

La validation des webhooks signés offre un certain nombre d'avantages en matière de sécurité, notamment :

• La possibilité de vérifier qu'une demande provient de Vonage
• S'assurer que le message n'a pas été altéré pendant son acheminement
• Défense contre l'interception et le rejeu ultérieur

Validation des webhooks signés

La validation des webhooks signés se fait en deux temps :

1. Verify the request
2. Verify the payload (optionnel)

Verify the request

Les webhooks incluront un JWT dans le fichier Authorization header. Utilisez la clé API incluse dans les revendications JWT pour identifier lequel de vos secrets de signature a été utilisé pour signer la demande. Le secret utilisé pour signer la demande correspond au secret de signature associé à l'en-tête api_key inclus dans les revendications JWT. Vous pouvez identifier votre secret de signature sur la page Tableau de bord. Il est recommandé que les secrets de signature ne soient pas inférieurs à 32 bits pour garantir leur sécurité.

Verify que la charge utile n'a pas été altérée en cours de route

Une fois que vous avez vérifié l'authenticité de la demande, vous pouvez éventuellement vérifier que la charge utile de la demande n'a pas été altérée en comparant un hachage SHA-256 de la charge utile à la balise payload_hash trouvé dans les revendications JWT. S'ils ne correspondent pas, c'est que la charge utile a été altérée pendant le transit. La vérification de la charge utile n'est nécessaire que si vous utilisez HTTP plutôt que HTTPS, car la sécurité de la couche de transport (TLS) empêche la falsification de la charge utile. Attaques MITM.

L'exemple de code ci-dessous montre comment vérifier la signature d'un webhook. Il est recommandé d'utiliser le protocole HTTPS, qui garantit que la demande et la réponse sont cryptées à la fois par le client et par le serveur.

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

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')

Exemple de JWT signé

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

En-tête JWT signé

Le contenu de l'en-tête JWT signé est décrit dans le tableau suivant :

Charge utile JWT signée

Le contenu de la charge utile du JWT signé est décrit dans le tableau suivant, en utilisant les valeurs incluses dans l'exemple de JWT signé présenté précédemment :

Tester les webhooks localement

Afin de tester le bon fonctionnement des webhooks sur votre application exécutée localement, vous devrez créer un tunnel sécurisé entre Vonage et votre application. Vous pouvez le faire à l'aide d'une application de tunnel sécurisé telle que Ngrok. Voir le Tester avec Ngrok pour plus d'informations.

Configuration du pare-feu

Si vous limitez le trafic entrant (y compris les accusés de réception), vous devez ajouter les adresses IP de Vonage à la liste des adresses IP approuvées de votre pare-feu. Vous trouverez plus d'informations à ce sujet dans notre base de connaissances :

• Gammes Voix IP
• Plages IP SMS
• Messages et plages IP d'envoi
• Nombre de plages IP Insight Advanced Async

Conseils pour déboguer les webhooks

Commencer modestement - Publiez le plus petit script possible auquel vous pouvez penser pour répondre à la réception du webhook et éventuellement imprimer des informations de débogage. Cela permet de s'assurer que l'URL est bien celle que l'on croit et que l'on peut voir la sortie ou les journaux de l'application.

Coder de manière défensive - Vérifiez que les valeurs de données existent et contiennent ce que vous attendez avant de les utiliser. En fonction de votre configuration, vous pourriez recevoir des données inattendues ; gardez donc toujours cela à l'esprit.

Voir des exemples - Vonage fournit des exemples mis en œuvre avec plusieurs piles technologiques dans le but d'aider le plus grand nombre de développeurs possible. Pour un exemple de code utilisant des webhooks, voir ce qui suit :

• Recevoir un SMS
• Traiter les récépissés de livraison
• Recevoir un appel entrant

Vous pouvez également consulter la section des extraits de code de la documentation de l'API que vous utilisez.

Voir aussi

• De plus amples informations sur les types de webhooks et les capacités des applications sont disponibles dans la rubrique Documentation relative à l'application.