Webhooks

Ein Webhook ist eine vom Partner angegebene URL, an die die RBM-Plattform Nachrichten und Ereignisse sendet. Diese URL fungiert 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 Ihren Webhook entweder auf Partner- oder auf Agent-Ebene konfigurieren.

  • Ihr Partner-Webhook gilt für jeden Agent, den Sie verwalten. Wenn Ihre Kundenservicemitarbeiter ein ähnliches Verhalten aufweisen oder Sie nur einen Kundenservicemitarbeiter haben, verwenden Sie den Partner-Webhook.
  • Agent-Webhooks gelten für einzelne Agents. Wenn Sie mehrere Agents mit unterschiedlichem Verhalten betreiben, können Sie für jeden Agent einen anderen Webhook festlegen.

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

Webhook für einen Agent konfigurieren

Nachrichten, die an Ihren Agent gesendet werden, werden an Ihren Partner-Webhook gesendet. Wenn Nachrichten für einen bestimmten Agent an einem anderen Webhook eingehen sollen, legen Sie einen Agent-Webhook fest.

  1. Öffnen Sie die Business Communications Developer Console und melden Sie sich mit Ihrem Google-Konto als RBM-Partner an.
  2. Klicken Sie auf den Agent.
  3. Klicken Sie auf Integrations (Integrationen).
  4. Klicken Sie für Webhook auf Konfigurieren.
  5. Geben Sie unter Webhook-Endpunkt-URL Ihre Webhook-URL ein, die mit „https://“ beginnt.
  6. Notieren Sie sich den Wert von clientToken. Sie benötigen sie, um zu bestätigen, dass Nachrichten, die Sie erhalten, von Google stammen.

  7. Konfigurieren Sie Ihren Webhook so, dass er eine POST-Anfrage mit dem angegebenen Parameter clientToken akzeptiert und eine 200 OK-Antwort mit dem Nur-Text-Wert des Parameters secret als Antworttext sendet.

    Wenn Ihr Webhook beispielsweise eine POST-Anfrage mit dem folgenden Textkörper empfängt:

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

    In diesem Fall sollte Ihr Webhook den Wert clientToken bestätigen und, falls 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 Entwicklerkonsole auf Bestätigen. Wenn RBM Ihren Webhook bestätigt, wird das Dialogfeld geschlossen.

Eingehende Nachrichten überprüfen

Da Webhooks Nachrichten von beliebigen Absendern empfangen können, sollten Sie überprüfen, ob eingehende Nachrichten von Google gesendet wurden, bevor Sie den Inhalt der Nachricht verarbeiten.

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

  1. Extrahieren Sie den X-Goog-Signature-Header der Nachricht. Dies ist eine gehashte, base64-codierte Kopie der Nutzlast des Nachrichtentexts.
  2. Base64-Dekodierung der RBM-Nutzlast im Element message.body der Anfrage.
  3. Erstellen Sie mit dem Client-Token Ihres Webhooks (das Sie bei der Einrichtung Ihres Webhooks angegeben haben) als Schlüssel einen SHA512-HMAC der Byte der Base64-decodierten Nachrichtennutzlast und Base64-codieren Sie das Ergebnis.
  4. Vergleichen Sie den X-Goog-Signature-Hash mit dem von Ihnen erstellten Hash.
    • Wenn die Hashes übereinstimmen, haben Sie bestätigt, dass die Nachricht von Google gesendet wurde.

    • Wenn die Hashes nicht übereinstimmen, prüfen Sie den Hashing-Prozess anhand einer bekannten Nachricht.

      Wenn Ihr Hashing-Prozess korrekt funktioniert und Sie eine Nachricht erhalten, die Ihrer Meinung nach betrügerisch an Sie gesendet wurde, kontaktieren Sie uns.

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

Nachrichtenverarbeitung

Wenn von einem Webhook etwas anderes als 200 OK zurückgegeben wird, gilt dies als Zustellungsfehler.

Entwickler müssen darauf achten, dass das Senden von Nachrichten mit hoher Rate Webhook-Benachrichtigungen mit hoher Rate 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. Beachten Sie Folgendes:

  • Prüfen Sie, ob Ihre DDoS-Schutzmaßnahmen so konfiguriert sind, dass sie die erwartete Rate von Webhook-Benachrichtigungen verarbeiten können.
  • Prüfen Sie, ob Ressourcen wie Datenbankverbindungspools nicht erschöpft sind und Zeitüberschreitungen oder 500-Antworten erzeugen.

Entwickler sollten ihre Systeme so gestalten, dass die Verarbeitung von RBM-Ereignissen asynchron erfolgt und nicht verhindert, dass der Webhook 200 OK zurückgibt.

Asynchrone Webhook-Verarbeitung

Es ist wichtig, das RBM-Ereignis nicht im Webhook selbst zu verarbeiten. 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 Wiederholungsmechanismus, wenn es eine andere Antwort als 200 OK von einem Webhook-Aufruf erhält. RBM erhöht die Wartezeit zwischen Wiederholungsversuchen auf maximal 600 Sekunden. Die Wiederholungsversuche werden 7 Tage lang fortgesetzt. Danach wird die Nachricht verworfen.

Auswirkungen von Webhooks auf Agent-Ebene

RBM stellt Nachrichten für einen Partner in einer Warteschlange an. Wenn ein Partner Webhooks auf Agentenebene verwendet, ist es wichtig zu bedenken, dass der Fehler eines Webhooks die Zustellung an andere Webhooks beeinträchtigt. Webhooks, die zu anderen Kundenservicemitarbeitern gehören, werden während des Backoff-Zeitraums einer fehlgeschlagenen Nachricht aufgerufen. Da fehlgeschlagene Nachrichten jedoch für erneute Versuche in die Warteschlange gestellt werden, sinken die allgemeinen Zustellungsraten und andere Kundenservicemitarbeiter sind betroffen.

Es ist wichtig, dass Entwickler dieses Modell verstehen und den Code entsprechend anpassen. Sie sollten Nachrichten so weit wie möglich annehmen und zur Verarbeitung in die Warteschlange stellen, um die Wahrscheinlichkeit eines Fehlers zu minimieren.

Nächste Schritte

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

Weiter
Dialogflow