API-Webhooks verifizieren

Einführung

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:

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

Verify sendet zwei Arten von Callbacks an Ihre Webhook-URL:

• Ereignis-Callback ("type": "event") — wird bei jedem Kanalversuch im Workflow gesendet. Erfordert eine Berechtigung auf Account-Ebene, mit Ausnahme der stillen Authentifizierung, bei der Ereignis-Callbacks standardmäßig gesendet werden.
• Zusammenfassung des Rückrufs ("type": "summary") — wird einmal pro Anfrage nach Abschluss des gesamten Arbeitsablaufs gesendet.

Ereignisse Rückruf

Ein Inbound-Event-Webhook, der bei jedem Kanalversuch innerhalb eines Verify-Workflows gesendet wird. Event-Callbacks sind für SMS, Sprache, WhatsApp, RCS, E-Mail, „Silent Authentication“ und „Silent Authentication Advanced“ verfügbar.

Ereignis-Callbacks werden über eine Berechtigung auf Account-Ebene aktiviert. Die „Silent Authentication“ generiert unabhängig von dieser Berechtigung weiterhin Ereignis-Callbacks. Für alle anderen Kanäle muss die Berechtigung auf Account-Ebene aktiviert sein. Um Ereignis-Callbacks für Ihren Account zu aktivieren, wenden Sie sich bitte an Ihren Kundenbetreuer oder den Support.

Dadurch wird der aktuelle Status eines Kanals mithilfe der status Feld:

• blocked - Die Anfrage wurde blockiert. Dies kann beispielsweise aufgrund von Velocity-Regeln geschehen oder wenn es sich bei der angegebenen Nummer um eine VoIP-Nummer handelt.
• failed - Die Anfrage ist fehlgeschlagen. Dies kann beispielsweise passieren, wenn die angegebene Nummer keine gültige Nummer war.
• expired - der Antrag nicht innerhalb der vorgegebenen Frist erledigt wurde.
• action_pending - Der Benutzer hat keine Maßnahmen ergriffen, um den Authentifizierungsprozess zu starten. Gilt nur für „Silent Authentication“ und „Silent Authentication Advanced“. Beispielsweise die check_url Die Funktion, die dem Benutzer für die stille Authentifizierung zur Verfügung steht, wurde noch nicht aufgerufen.

{
   "request_id": "c11236f4-00bf-4b89-84ba-88b25df97315",
   "triggered_at": "2020-01-01T14:00:00.000Z",
   "type": "event",
   "channel": "sms",
   "channel_order": 2,
   "status": "expired",
   "channel_initiated_at": "2020-01-01T14:00:05.000Z",
   "channel_finalized_at": "2020-01-01T14:00:10.000Z",
   "client_ref": "my-personal-ref"
}

Stille Authentifizierung & Stille Authentifizierung – Fortgeschritten

Bei „Silent Authentication“ und „Silent Authentication Advanced“ ist die anfängliche Ereignis-Callback enthält ein action_pending Status und ein action Objekt, das die check_url Das Gerät des Benutzers muss einen Anruf tätigen, um die Überprüfung abzuschließen:

{
   "request_id": "c11236f4-00bf-4b89-84ba-88b25df97315",
   "triggered_at": "2020-01-01T14:00:00.000Z",
   "type": "event",
   "channel": "silent_auth",
   "status": "action_pending",
   "mode": "advanced",
   "action": {
      "type": "check",
      "check_url": "https://api.nexmo.com/v2/verify/:request_id/silent-auth/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 Verifizierungsanfrage. Zunächst wurde eine stille Authentifizierung versucht, die jedoch vor Abschluss abgebrochen wurde. Dann wurde eine SMS versucht, die jedoch ablief. Anschließend 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": "silent_auth",
         "initiated_at": "2020-01-01T14:00:00.000Z",
         "status": "cancelled",
         "mode": "advanced"
      },
      {
         "channel": "sms",
         "initiated_at": "2020-01-01T14:05:00.000Z",
         "status": "expired"
      },
      {
         "channel": "whatsapp",
         "initiated_at": "2020-01-01T14:10:00.000Z",
         "status": "completed"
      },
      {
         "channel": "voice",
         "initiated_at": "2020-01-01T14:15: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.