Webhooks

Ein Webhook ist eine vom Partner angegebene URL, unter der die RBM-Plattform Nachrichten und Ereignisse veröffentlicht. Diese URL dient als Endpunkt, der HTTPS-POST-Anfragen mit Daten zu den Ereignissen empfängt. Das bedeutet, dass Daten sicher über HTTPS an Ihre Anwendung gesendet werden.

Eine Webhook-URL könnte so aussehen: https://[your company name].com/api/rbm-events. Sobald Sie Ihren Webhook konfiguriert haben, können Sie Nachrichten und Ereignisse empfangen.

Partner-Webhooks und Agent-Webhooks

Sie können den Webhook entweder auf Partner- oder auf Kundenservicemitarbeiterebene konfigurieren.

  • Der Partner-Webhook gilt für alle von dir verwalteten Kundenservicemitarbeiter. Wenn deine Kundenservicemitarbeiter ein ähnliches Verhalten zeigen oder du nur einen Kundenservicemitarbeiter hast, verwende den Partner-Webhook.
  • Agent-Webhooks gelten für einzelne Kundenservicemitarbeiter. Wenn Sie mehrere Bots mit unterschiedlichem Verhalten verwenden, können Sie für jeden Bot einen anderen Webhook festlegen.

Wenn Sie sowohl einen Partner- als auch einen Kundenservicemitarbeiter-Webhook konfiguriert haben, hat der Webhook für den Kundenservicemitarbeiter für den entsprechenden Kundenservicemitarbeiter Vorrang. Der Partner-Webhook gilt dagegen für alle Kundenservicemitarbeiter, die keinen eigenen Webhook haben.

Agent-Webhook konfigurieren

Sie erhalten Nachrichten, die an Ihren Kundenservicemitarbeiter über Ihren Partnerwebhook gesendet werden. Wenn Nachrichten für einen bestimmten Kundenservicemitarbeiter stattdessen an einem anderen Webhook ankommen sollen, legen Sie einen Webhook für Kundenservicemitarbeiter fest.

  1. Öffnen Sie die Business Communications Developer Console und melden Sie sich mit dem Google-Konto Ihres RBM-Partners an.
  2. Klicken Sie auf Ihren Kundenservicemitarbeiter.
  3. Klicken Sie auf Integrations (Integrationen).
  4. Klicken Sie bei Webhook auf Konfigurieren.
  5. Geben Sie unter Webhook-Endpunkt-URL die Webhook-URL ein, die mit „https://“ beginnt.
  6. Notieren Sie sich den Wert von clientToken. Sie benötigen sie, um zu prüfen, ob die von Ihnen empfangenen Nachrichten von Google stammen.

  7. Konfigurieren Sie Ihren Webhook so, dass er eine POST-Anfrage mit dem angegebenen clientToken-Parameter akzeptiert und eine 200 OK-Antwort mit dem Klartextwert des secret-Parameters als Antworttext zurücksendet.

    Angenommen, Ihr Webhook empfängt eine POST-Anfrage mit dem folgenden Inhalt:

    {
  "clientToken":"SJENCPGJESMGUFPY",
  "secret":"1234567890"
}

    sollte Ihr Webhook den Wert clientToken bestätigen und, wenn clientToken korrekt ist, eine 200 OK-Antwort mit 1234567890 als Antworttext zurückgeben:

    // clientToken from Configure
const myClientToken = "SJENCPGJESMGUFPY";

// Example endpoint
app.post("/rbm-webhook", (req, res) => {
  const msg = req.body;
  if (msg.clientToken === myClientToken) {
      res.status(200).send(msg.secret);
      return;
  }
  res.send(400);
});

  8. Klicken Sie in der Developer Console auf Bestätigen. Wenn RBM Ihren Webhook bestätigt hat, wird das Dialogfeld geschlossen.

Eingehende Nachrichten prüfen

Da Webhooks Nachrichten von beliebigen Absendern empfangen können, sollten Sie vor der Verarbeitung des Nachrichteninhalts prüfen, ob die eingehenden Nachrichten von Google gesendet wurden.

So prüfen Sie, ob Google eine Nachricht gesendet hat, die Sie erhalten haben:

  1. Extrahieren Sie die X-Goog-Signature-Kopfzeile der Nachricht. Dies ist eine gehashte, base64-codierte Kopie der Nutzlast des Nachrichtentexts.
  2. Decodiere die RBM-Nutzlast im Element message.body der Anfrage mit Base64.
  3. Erstelle mit dem Client-Token deines Webhooks (das du bei der Einrichtung des Webhooks angegeben hast) als Schlüssel einen SHA512-HMAC aus den Bytes der Base64-decodierten Nachrichtennutzlast und codiere das Ergebnis mit Base64.
  4. Vergleichen Sie den X-Goog-Signature-Hash mit dem von Ihnen erstellten Hash.
    • Wenn die Hash-Werte übereinstimmen, haben Sie bestätigt, dass Google die Nachricht gesendet hat.

    • Wenn die Hash-Werte nicht übereinstimmen, prüfen Sie Ihren Hash-Prozess anhand einer fehlerfreien Nachricht.

      Wenn Ihr Hash-Verfahren ordnungsgemäß funktioniert und Sie eine Nachricht erhalten, die Ihrer Meinung nach betrügerisch ist, kontaktieren Sie uns bitte.

Node.js

  if ((requestBody.hasOwnProperty('message')) && (requestBody.message.hasOwnProperty('data'))) {
    // Validate the received hash to ensure the message came from Google RBM
    let userEventString = Buffer.from(requestBody.message.data, 'base64');
    let hmac = crypto.createHmac('sha512', CLIENT_TOKEN);
    let data = hmac.update(userEventString);
    let genHash = data.digest('base64');
    let headerHash = req.header('X-Goog-Signature');

    if (headerHash === genHash) {
      let userEvent = JSON.parse(userEventString);

      console.log('userEventString: ' + userEventString);
      handleMessage(userEvent);
    } else {
      console.log('hash mismatch - ignoring message');
    }
  }

  res.sendStatus(200);

Nachrichtenverwaltung

Wenn ein Webhook etwas anderes als 200 OK zurückgibt, gilt dies als Übermittlungsfehler.

Entwickler müssen sich darüber im Klaren sein, dass das Senden von Nachrichten in hoher Rate auch eine hohe Rate an Webhook-Benachrichtigungen generiert. Sie müssen ihren Code so gestalten, dass Benachrichtigungen mit der erwarteten Rate verarbeitet werden können. Entwickler müssen Situationen berücksichtigen, die zu Fehlerantworten führen können, einschließlich 500-Antworten aus ihrem Webcontainer, Zeitüberschreitungen oder Upstream-Fehler. Folgende Punkte sollten Sie dabei berücksichtigen:

  • Achten Sie darauf, dass Ihre DDoS-Schutzmaßnahmen so konfiguriert sind, dass sie die erwartete Anzahl von Webhook-Benachrichtigungen verarbeiten können.
  • Achten Sie darauf, dass Ressourcen wie Datenbankverbindungspools nicht aufgebraucht werden und zu Zeitüberschreitungen oder 500-Antworten führen.

Entwickler müssen dafür sorgen, dass die Verarbeitung von RBM-Ereignissen asynchron erfolgt und nicht verhindert, dass der Webhook 200 OK zurückgibt.

Asynchrone Webhook-Verarbeitung

Das RBM-Ereignis darf nicht im Webhook selbst verarbeitet werden. Fehler oder Verzögerungen bei der Verarbeitung können sich auf den Webhook-Rückgabecode auswirken:

Synchrone Webhook-Verarbeitung

Verhalten bei Zustellungsfehlern

RBM verwendet einen Backoff- und Wiederholmechanismus, wenn es eine andere Antwort als 200 OK von einem Webhook-Aufruf erhält. RBM erhöht die Wartezeit zwischen den Wiederholungen auf maximal 600 Sekunden. Die Wiederholungen werden 7 Tage lang fortgesetzt, bevor die Nachricht gelöscht wird.

Auswirkungen von Webhooks auf Agentenebene

RBM stellt Nachrichten für einen Partner in einer Warteschlange an. Wenn ein Partner Webhooks auf Kundenservicemitarbeiterebene verwendet, muss er beachten, dass sich ein Fehler bei einem Webhook auf die Zustellung an andere Webhooks auswirkt. Webhooks anderer Kundenservicemitarbeiter werden während des Backoff-Zeitraums einer fehlgeschlagenen Nachricht aufgerufen. Da fehlgeschlagene Nachrichten jedoch für einen erneuten Versuch in die Warteschlange gestellt werden, sinken die Gesamtauslieferungsraten und andere Kundenservicemitarbeiter sind betroffen.

Es ist wichtig, dass Entwickler dieses Modell verstehen und entsprechend programmieren. Akzeptieren Sie nach Möglichkeit Nachrichten und stellen Sie sie zur Verarbeitung in die Warteschlange, um die Wahrscheinlichkeit zu minimieren, dass ein Fehler zurückgegeben wird.

Nächste Schritte

Nachdem Sie den Webhook konfiguriert haben, kann Ihr Kundenservicemitarbeiter Nachrichten von Ihren Testgeräten empfangen. Senden Sie eine Nachricht, um die Einrichtung zu bestätigen.

Weiter
Dialogflow