Webhook

Die GetProcess-Artikel in dieser Dokumentation beschreiben eine Möglichkeit, den Status eines Prozesses über den Aufruf eines Endpunkts abzurufen. Auf diese Weise wird Polling durchgeführt, um Informationen über die erstellten Prozesse zu erhalten. Das bedeutet, dass der Endpunkt für denselben Prozess mehrfach aufgerufen werden kann, um den aktuellsten Status zu erhalten.

Durch die Verwendung von Webhooks ist es möglich, einen bestimmten Endpunkt zu benachrichtigen, jedes Mal wenn sich der Status eines Prozesses ändert.

Was ist ein Webhook?

Ein Webhook ist ein systemischer Benachrichtigungsdienst, der die asynchrone Integration zwischen Systemen ermöglicht, wobei ein System das andere über einen Trigger benachrichtigt. Auf diese Weise können Webhooks Systeme mit den aktuellsten Informationen auf dem neuesten Stand halten, ohne dass ein ständiges Polling zur Überprüfung auf Updates erforderlich ist.

So konfigurieren Sie den Webhook

Um den Webhook zu konfigurieren, werden folgende Informationen benötigt:

• Benachrichtigungs-URL: Dies ist der Endpunkt, den Unico für Benachrichtigungen über Statusaktualisierungen verwendet.
• Authentifizierungstyp: Dies ist die Methode, mit der der Aufruf des Endpunkts authentifiziert wird. Folgende Optionen stehen zur Verfügung:
  • OAuth2;
  • Basic Authorization;
  • API Key;
  • Keine Authentifizierung.
• Für OAuth2 müssen folgende Informationen angegeben werden:
  • Webhook-endpoint;
  • OAuth2-Anbieter-URL;
  • OAuth2-Anbieter-ClientId;
  • OAuth2-Anbieter-Secret.
• Für Basic Authorization muss die Angabe im Format user:pass gesendet werden.
• Für API Key sind zwei Formate möglich:
  • header:value, wenn ein bestimmter Header-Name gewünscht wird;
  • value, wenn der gewünschte Header Authorization ist.
• Wiederholungseinstellungen: Diese geben die Anzahl der Versuche bei einem Fehlschlag des Endpunktaufrufs an:
  • Maximale Anzahl der Versuche;
  • Intervall zwischen den Versuchen (in Sekunden);
  • Rate Limit: Maximale Anzahl gleichzeitiger Übermittlungen (max.: 500);
  • Timeout: Maximale Wartezeit auf die Antwort des Endpunkts (in Sekunden).
• Zu benachrichtigende Status: Sie können sich für bestimmte Status anmelden, um Benachrichtigungen zu erhalten. Dazu gehören:
  • approved: Transaktion genehmigt;
  • processing: Transaktion in Bearbeitung;
  • inconclusive: Wir konnten keine eindeutige Validierung durchführen;
  • shared: Transaktion geteilt, wartet auf Übermittlung;
  • skipped: Die Person hat die biometrische Erfassung im Ablauf übersprungen;
  • unknown-share: Die Person hat angegeben, den Kauf nicht wiederzuerkennen;
  • absent-holder: Der Karteninhaber ist bei der Erfassung nicht anwesend;
  • expired: Die Person hat die Erfassung nicht innerhalb der festgelegten Zeit abgeschlossen, und die Transaktion ist abgelaufen.

Zur Authentifizierung

Die API kann durch eine Authentifizierungsmethode wie Basic Authentication oder API Key geschützt werden. Zum zusätzlichen Schutz kann außerdem eine Liste gültiger IPs für den Zugriff definiert werden.

Integration mit Verifizierung ohne physische Karte

Bei der Konfiguration eines Webhooks auf der Plattform können Sie Informationen über die Prozesse durch Benachrichtigungen erhalten, die an einen Endpunkt der von Ihnen entwickelten API gesendet werden, um diese Updates zu empfangen.

Die von der Plattform an die API gesendeten Informationen umfassen:

• ID: Transaktions-ID;
• Status: Transaktionsstatus;
• HasIdentityChanged: Ob bei der Transaktion eine Identitätsänderung aufgetreten ist (optional).

Hinweis

Beachten Sie, dass es möglich ist, über die Webhook-Konfiguration auszuwählen, über welche Status der Kunde benachrichtigt werden möchte. Nach dem Senden dieser Informationen sollte die erwartete Antwort synchron erfolgen.

Anfragen

Die Anfrage muss über eine POST-Methode an eine REST-API erfolgen, was das Senden der Informationen einfacher und sicherer macht. Alle Felder müssen erforderlich sein. Der Anfragetext sollte die Transaktions-ID und den Status akzeptieren, wie im folgenden Beispiel gezeigt:

{
  "id": "8263a268-5388-492a-bca2-28e1ff4a69f0",
  "status": "approved",
  "hasIdentityChanged": false
}

Antwort

Die Antwort sollte synchron erfolgen. Der Status für erfolgreiche Anfragen sollte im Bereich von 200 bis 299 liegen. Jeder andere Status wird als Fehlschlag gewertet, und Verifizierung ohne physische Karte wird weitere Benachrichtigungsversuche unternehmen (mit exponentiellem Backoff dazwischen), bis eine 2xx-Antwort empfangen wird oder die maximale Anzahl an Versuchen erreicht ist.

Antwortstatus

Derzeit gibt es eine bestimmte Menge an Status, diese kann sich jedoch in Zukunft ändern. Es wird daher empfohlen, die Status, an denen der Kunde interessiert ist, um Maßnahmen zu ergreifen, konfigurierbar zu machen. Wenn beispielsweise beabsichtigt ist, jedes Mal eine Aktion auszulösen, wenn eine Erfassung erfolgreich abgeschlossen wurde, geschieht dies derzeit beim Status „processing“. Da sich dies jedoch in Zukunft ändern könnte, wird empfohlen, den Status, der eine erfolgreiche Erfassung anzeigt, im System konfigurierbar zu machen, damit eine zukünftige Änderung zum Status „captured“ einfach umgesetzt werden kann.

Außerdem empfehlen wir, spezifische Aktionen für spezifische Status sowie eine allgemeine Aktion für den Fall vorzusehen, dass der Status nicht erkannt wird (zum Beispiel unter der Annahme, dass alles, was von „processing“ und „approved“ abweicht, als nicht eindeutig gilt). Dies ist wichtig, da in Zukunft neue Status auftreten können und der Webhook dadurch nicht beeinträchtigt werden soll.

Wichtige Hinweise

Achten Sie bei der Entwicklung der API, die Verifizierung ohne physische Karte zur Benachrichtigung über Statusänderungen verwendet, auf folgende Aspekte:

Rate limit — Um eine Überlastung Ihrer Ressourcen bei einer hohen Anzahl von Transaktionen zu vermeiden, kann eine Obergrenze für die Anzahl der Aufrufe des Endpunkts festgelegt werden.

Error Rate — Die Fehlerrate (Antworten außerhalb des Bereichs [200, 299]) sollte stets niedrig gehalten werden. Andernfalls wird der Webhook-Durchsatz automatisch reduziert, und diese Reduzierung kann in Kombination mit dem Wiederholungsmechanismus zu einer längeren Ausführungszeit für neue Webhooks führen.

Idempotence — Die aktuelle Webhook-Implementierung garantiert eine mindestens einmalige Zustellung (at-least-once), sodass derselbe Status mehr als einmal gemeldet werden kann. Die Implementierung des Endpunkts sollte daher idempotent erfolgen.

Fallback — Im Falle einer Nichtverfügbarkeit des Webhook-Dienstes wird empfohlen, eine Fallback-Methode bereitzustellen, damit Sie die Transaktionsstatus weiterhin innerhalb der festgelegten Antwortzeit abrufen können. Die Endpunktabfrage wird im Abschnitt API-Referenz dieser Dokumentation beschrieben.