Webhaken

Webhooks sind eine Erweiterung einer API, aber anstatt dass Ihr Code Daten von unserer API-Plattform anfordert, sendet Vonage die Daten an Sie. Die Daten werden in einer Webanforderung an Ihre Anwendung gesendet. Ein Webhook kann das Ergebnis eines früheren API-Aufrufs sein (diese Art von Webhook wird auch als "Callback" bezeichnet), wie z. B. eine asynchrone Anfrage an die Number Insight API. Webhooks werden auch verwendet, um Ihre Anwendung über Ereignisse wie einen eingehenden Anruf oder eine Nachricht zu benachrichtigen.

Da die Vonage-Server in der Lage sein müssen, Daten über Webhooks an Ihre Anwendung zu senden, müssen Sie einen Webserver einrichten, der die eingehenden HTTP-Anfragen empfängt. Sie müssen auch die URL jedes Webhooks auf Ihrem Webserver angeben, damit Daten an jeden einzelnen gesendet werden können.

Webhooks Arbeitsablauf

Bei Webhooks ist es wichtig, dass die URL, an die die Webhooks gesendet werden sollen, konfiguriert ist. Wenn Daten verfügbar sind, sendet Vonage den Webhook als HTTP-Anfrage an Ihre Anwendung. Ihre Anwendung sollte mit einem HTTP-Erfolgscode antworten, um anzuzeigen, dass sie die Daten erfolgreich empfangen hat.

Der Prozess sieht in etwa so aus:

Webhooks bieten einen bequemen Mechanismus, mit dem Vonage Informationen zu Ereignissen wie einem eingehenden Anruf oder einer Nachricht oder einer Änderung des Anrufstatus an Ihre Anwendung senden kann. Sie können auch verwendet werden, um Folgeinformationen zu senden, wie z. B. eine Zustellungsbestätigung, die einige Zeit nach der Anfrage, auf die sie sich bezieht, zur Verfügung stehen kann.

Welche APIs unterstützen Webhooks?

Informationen, die aus Anfragen an unterstützte Vonage-APIs resultieren, werden in einer HTTP-Anfrage an Ihren Webhook-Endpunkt auf einem HTTP-Server gesendet. Um Ihren Webhook-Endpunkt zu konfigurieren, besuchen Sie bitte die Dashboard von Vonage.

Vonage sendet und empfängt die folgenden Informationen über Webhooks:

Webhook-Endpunkte festlegen

Webhooks werden verwendet, um eingehende Nachrichten und Zustellungsquittungen zu übermitteln.

Eingehende Nachrichten

Um den für eingehende Nachrichten verwendeten Webhook einzurichten, gehen Sie zum Ihre Numbers Abschnitt des Vonage Dashboards. Klicken Sie auf "Bearbeiten" für die virtuelle Nummer und legen Sie die Rückruf-URL.

Sie können auch die Vonage CLI um den Endpunkt für eingehende Nachrichten für eine einzelne Nummer festzulegen.

Lieferscheine

Siehe die Lieferscheine Anleitung in der SMS-Dokumentation.

Empfangen von Webhooks

Zur Interaktion mit Vonage-Webhooks:

1. Erstellen Sie einen Vonage Account.
2. Schreiben Sie Skripte, um die von Vonage gesendeten oder angeforderten Informationen zu verarbeiten. Ihr Server muss auf eingehende Nachrichten von Vonage mit einem Erfolgsstatuscode antworten (jeder Statuscode zwischen 200 OK und 205 Reset Content). Alles andere als ein 2xx Code veranlasst die Vonage-Server, die Rückrufzustellung erneut zu versuchen.
3. Veröffentlichen Sie Ihre Skripte, indem Sie sie auf einem Server bereitstellen (für die lokale Entwicklung versuchen Sie Ngrok).
4. Konfigurieren Sie einen Webhook-Endpunkt in der API, die Sie verwenden möchten.
5. Führen Sie eine Aktion durch (z. B. das Senden einer SMS), die diesen Webhook auslöst.

Die Informationen über Ihre Anfrage werden dann an Ihren Webhook-Endpunkt gesendet.

Dekodierung signierter Webhooks

Die Webhook-Signierung wird aktiviert durch Standard für die Messages-, Dispatch-, Verify- und Voice APIs. Sie bieten eine Methode, mit der Ihre Anwendung überprüfen kann, ob eine Anfrage von Vonage kommt und die Nutzdaten während der Übertragung nicht manipuliert wurden. Beim Empfang einer Anfrage enthält der eingehende Webhook ein JWT-Token im Autorisierungs-Header, das mit Ihrem Signaturgeheimnis signiert ist.

ANMERKUNG: Bei bereits erstellten Voice Applications ist Signed Webhooks standardmäßig deaktiviert. Um sie manuell zu aktivieren, gehen Sie zu den Anwendungseinstellungen im Dashboard, klicken Sie auf den Link "Erweiterte Funktionen anzeigen" im Abschnitt "Sprachfunktionen" und aktivieren Sie dann die Option "Signierte Webhooks". Signierte Webhooks verwenden prüfen:

Sie können diese Funktion auch für neue Anwendungen deaktivieren (nicht empfohlen, nur in Ausnahmefällen).

Die Validierung signierter Webhooks bietet eine Reihe von Sicherheitsvorteilen, darunter:

• Die Möglichkeit zu verifizieren, dass eine Anfrage von Vonage stammt
• Sicherstellung, dass die Nachricht während der Übermittlung nicht manipuliert wurde
• Verteidigung gegen Abfangen und spätere Wiederholung

Validierung signierter Webhooks

Die Validierung signierter Webhooks besteht aus zwei Teilen:

1. Verify der Anfrage
2. Verify der Nutzlast (optional)

Verify der Anfrage

Webhooks enthalten ein JWT in der Authorization Kopfzeile. Verwenden Sie den in den JWT-Ansprüchen enthaltenen API-Schlüssel, um festzustellen, welches Ihrer Signaturgeheimnisse zum Signieren der Anforderung verwendet wurde. Das zum Signieren der Anforderung verwendete Geheimnis entspricht dem Signaturgeheimnis, das mit dem api_key in den JWT-Ansprüchen enthalten. Sie können Ihr Signaturgeheimnis auf der Dashboard. Es wird empfohlen, dass die Signaturgeheimnisse nicht weniger als 32 Bit betragen, um ihre Sicherheit zu gewährleisten.

Verify, dass die Nutzlast während des Transports nicht manipuliert wurde

Nachdem Sie die Authentizität der Anfrage überprüft haben, können Sie optional überprüfen, dass die Nutzdaten der Anfrage nicht manipuliert wurden, indem Sie einen SHA-256-Hash der Nutzdaten mit dem payload_hash Feld in den JWT-Ansprüchen gefunden. Wenn sie nicht übereinstimmen, wurde die Nutzlast während der Übertragung manipuliert. Sie müssen die Nutzdaten nur verifizieren, wenn Sie HTTP und nicht HTTPS verwenden, da TLS (Transport Layer Security) verhindert, dass MITM-Angriffe.

Das folgende Codebeispiel zeigt, wie eine Webhook-Signatur verifiziert wird. Es wird empfohlen, das HTTPS-Protokoll zu verwenden, da es sicherstellt, dass die Anfrage und die Antwort sowohl auf der Client- als auch auf der Serverseite verschlüsselt sind.

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

Beispiel für ein signiertes JWT

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

Signierter JWT-Header

Der Inhalt des signierten JWT-Headers wird in der folgenden Tabelle beschrieben:

Signierte JWT-Nutzdaten

Der Inhalt des signierten JWT-Payloads wird in der folgenden Tabelle beschrieben, wobei die Werte verwendet werden, die in dem zuvor gezeigten signierten JWT-Beispiel enthalten sind:

Webhooks lokal testen

Um die korrekte Funktion von Webhooks in Ihrer lokal laufenden Anwendung zu testen, müssen Sie einen sicheren Tunnel zwischen Vonage und Ihrer Anwendung erstellen. Dies können Sie mit einer sicheren Tunnelanwendung tun, wie z.B. Ngrok. Siehe die Testen mit Ngrok für weitere Informationen.

Konfigurieren der Firewall

Wenn Sie den eingehenden Datenverkehr (einschließlich Lieferscheine) beschränken, müssen Sie die IP-Adressen von Vonage in die Liste der zugelassenen IP-Adressen Ihrer Firewall aufnehmen. Weitere Informationen hierzu finden Sie in unserer Wissensdatenbank:

• Sprach-IP-Bereiche
• SMS-IP-Bereiche
• Nachrichten und Versand-IP-Bereiche
• Number Insight Erweiterte Async-IP-Bereiche

Tipps zur Fehlersuche bei Webhooks

Klein anfangen - Veröffentlichen Sie das kleinstmögliche Skript, das Sie sich vorstellen können, um zu reagieren, wenn der Webhook empfangen wird, und geben Sie eventuell einige Debug-Informationen aus. So stellen Sie sicher, dass die URL das ist, wofür Sie sie halten, und dass Sie die Ausgaben oder Protokolle der Anwendung sehen können.

Defensiver Code - Vergewissern Sie sich, dass die Datenwerte vorhanden sind und das enthalten, was Sie erwartet haben, bevor Sie sie verwenden. Je nach Ihrer Einrichtung könnten Sie unerwartete Daten erhalten, denken Sie also immer daran.

Sehen Sie sich Beispiele an - Vonage bietet Beispiele, die mit verschiedenen Technologie-Stacks implementiert wurden, um so viele Entwickler wie möglich zu unterstützen. Ein Beispiel für Code, der Webhooks verwendet, finden Sie im Folgenden:

• Empfangen einer SMS
• Lieferquittungen abwickeln
• Eingehende Anrufe entgegennehmen

Sie können auch den Abschnitt mit den Codeschnipseln in der Dokumentation für die von Ihnen verwendete API prüfen.

Siehe auch

• Weitere Informationen zu Webhook-Typen und Anwendungsmöglichkeiten finden Sie in der Dokumentation der Applications.