API-Webhooks verifizieren

Webhaken sind eine Erweiterung einer API - anstatt dass Ihr Code Daten von unserer API-Plattform anfordert, sendet Vonage Ihnen die Daten über eine Webanforderung an Ihre Anwendung. Der Verify API-Webhook empfängt Statusaktualisierungen zu Ihren Anfragen und ist das Ergebnis eines früheren API-Aufrufs - diese Art von Webhook wird auch als "Callback" bezeichnet.

Empfangen von Webhooks

Damit die Vonage-Server Daten über Webhooks an Ihre Anwendung senden können, 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.

Um Verify-Webhooks zu verwenden:

  1. Erstellen Sie einen Vonage Account.
  2. Schreiben Sie Skripte, um die von Vonage gesendeten oder angeforderten Informationen zu verarbeiten. Ihr Server muss mit einer 200 oder 204 HTTP-Antwort, als etwas anderes als eine 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 Ihren Verify Webhook-Endpunkt.
  5. Eine Aktion durchführen (z. B. Senden einer SMS-Bestätigungsanfrage), die diesen Webhook auslösen.

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

Konfigurieren Sie Ihre Verify Webhook-URLs

Die Verify API unterstützt einen Status-Webhook, der in Ihrem Applikationseinstellungen im Dashboard für Entwickler:

Webhooks can be configured on the customer dashboard

Damit können Sie Statusaktualisierungen (z. B. Fortschritts- oder Abschlussereignisse) für Ihre Verify-Anfragen senden.

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 Testen mit Ngrok für weitere Informationen.

Signierte Webhooks

Verify Webhooks sind standardmäßig signiert. Mit signierten Webhooks kann Ihre Anwendung verifizieren, dass 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.

Weitere Informationen zur Dekodierung signierter Webhooks finden Sie unter hier.

Arten von Rückrufen

Ereignisse Rückruf

Ein Webhook für eingehende Ereignisse. Dieser zeigt das Endergebnis Ihrer Anfrage unter Verwendung der status Feld:

  • completed - die Anfrage wurde abgeschlossen und der Benutzer wurde erfolgreich verifiziert.
  • blocked - die Anfrage wurde aufgrund von Geschwindigkeitsregeln blockiert, oder die angegebene Nummer ist eine VOIP-Nummer.
  • failed - ist die Anfrage fehlgeschlagen, da die angegebene Nummer keine gültige Nummer war.
  • expired - der Antrag nicht innerhalb der vorgegebenen Frist erledigt wurde.
  • user_rejected - der Benutzer eine falsche PIN eingegeben hat.
  • cancelled - der Benutzer hat die Anfrage abgebrochen, bevor der Authentifizierungsprozess abgeschlossen war.
  • action_pending - der Benutzer hat keine Aktion durchgeführt, um das Authentifizierungsverfahren zu starten. Zum Beispiel kann der check_url die dem Benutzer gegeben wird, um die stille Authentifizierung zu beginnen, ist bereits erfolgt.
{
   "request_id": "c11236f4-00bf-4b89-84ba-88b25df97315",
   "triggered_at": "2020-01-01T14:00:00.000Z",
   "type": "event",
   "channel": "sms",
   "status": "completed",
   "finalized_at": "2020-01-01T14:00:00.000Z",
   "client_ref": "my-personal-ref"
}

Stille Authentifizierung

Als Teil einer Stille Authentifizierung Anfrage, erhalten Sie eine Ereignisrückruf zu Ihrem Webhook - zum Beispiel:

{
   "request_id": "c11236f4-00bf-4b89-84ba-88b25df97315",
   "triggered_at": "2020-01-01T14:00:00.000Z",
   "type": "event",
   "channel": "silent_auth",
   "status": "action_pending",
   "action": [
      {
         "type": "check",
         "check_url": "https://eu.api.silent.auth/phone_check/v0.1/checks/:request_id/redirect"
      }
   ]
}

Zusammenfassung Rückruf

Zusammenfassungsrückrufe enthalten eine eingehende Statusaktualisierung für eine bestimmte Anfrage. Wie Sie im folgenden Beispiel sehen können, gibt es zwei Statusfelder - das erste ist der Status der gesamten Anfrage, und die anderen zeigen das Ergebnis jedes im Workflow verwendeten Kanals.

Für die Anfrage gibt es sechs verschiedene Statuswerte, die Sie sehen können:

  • completed - die Anfrage wurde abgeschlossen und der Benutzer wurde erfolgreich verifiziert.
  • failed - die Anfrage ist fehlgeschlagen, da die angegebene Nummer keine gültige Nummer oder keine mobile IP war.
  • expired - das Ersuchen nicht innerhalb der vorgegebenen Zeit abgeschlossen wurde.
  • user_rejected - Der Benutzer gab dreimal eine falsche PIN ein, wodurch der Arbeitsablauf abgebrochen wurde.
  • blocked - die Anfrage wurde aufgrund von Geschwindigkeitsregeln blockiert, oder die angegebene Nummer ist eine VOIP-Nummer.
  • cancelled - der Benutzer hat die Anfrage abgebrochen, bevor der Authentifizierungsprozess abgeschlossen war.

Im Arbeitsablauf gibt es sieben verschiedene Statuswerte, die Sie bei der Verwendung der API sehen können:

  • unused - der Kanal wurde nicht verwendet, da der Auftrag von einem früheren Kanal im Arbeitsablauf umgewandelt wurde.
  • completed - der Kanal wurde verwendet und führte zu einer erfolgreichen Überprüfung.
  • failed - ein im Arbeitsablauf definierter Kanal ist fehlgeschlagen, weil die angegebene Nummer keine gültige Nummer oder keine mobile IP war oder das Land, in dem sich der Benutzer befand, von Verify nicht abgedeckt wird.
  • expired - ein im Workflow definierter Kanal abgelaufen ist, da das OTP nicht innerhalb der vorgegebenen Frist eingegeben wurde.
  • blocked - Der SMS-/Sprachkanal wurde aufgrund von Geschwindigkeitsregeln blockiert.
  • user_rejected - Der Benutzer hat dreimal einen falschen Pin eingegeben, wodurch der Arbeitsablauf für den verwendeten Kanal abgebrochen wurde.
  • cancelled- der im Workflow definierte Authentifizierungsprozess eines bestimmten Channels abgebrochen wurde, während er noch lief.

Dieses Beispiel zeigt eine Aktualisierung für eine abgeschlossene Überprüfungsanfrage. Der erste Kanal hat versucht, SMS zu verwenden, aber die Anfrage ist abgelaufen. Danach wurde WhatsApp verwendet und der Benutzer wurde erfolgreich verifiziert. Da der Sprachkanal nicht versucht wurde, wird der Status wie folgt angezeigt unused.

{
   "request_id": "c11236f4-00bf-4b89-84ba-88b25df97315",
   "submitted_at": "2020-01-01T14:00:00.000Z",
   "status": "completed",
   "type": "summary",
   "channel_timeout": 300,
   "workflow": [
      {
         "channel": "sms",
         "initiated_at": "2020-01-01T14:00:00.000Z",
         "status": "expired"
      },
      {
         "channel": "whatsapp",
         "initiated_at": "2020-01-01T14:02:00.000Z",
         "status": "completed"
      },
      {
         "channel": "voice",
         "initiated_at": "2020-01-01T15:05:00.000Z",
         "status": "unused"
      }
   ],
   "client_ref": "my-personal-ref"
}

Um die Anfrage zur stillen Authentifizierung abzuschließen, müssen Sie die check_url und zur Authentifizierung an den Client weitergeben.