Webhooks

Ein Webhook ist ein von einem Partner erstellter HTTPS-Callback, der angibt, wie Ihr Kundenservicemitarbeiter auf Nachrichten und Ereignisse reagieren soll. Nachdem Sie den Webhook konfiguriert haben, können Sie mit dem Empfangen von Nachrichten und Ereignissen beginnen.

Partner-Webhooks und Agent-Webhooks

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

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

Agent-Webhook konfigurieren

Sie erhalten Nachrichten, die an Ihren Kundenservicemitarbeiter über Ihren Partnerwebhook gesendet wurden. Wenn Nachrichten für einen bestimmten Agent stattdessen an einen anderen Webhook gesendet werden sollen, legen Sie einen Agent-Webhook 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 den Agent.
  3. Klicken Sie auf Integrations (Integrationen).
  4. Klicken Sie unter Webhook auf Configure (Konfigurieren).
  5. Geben Sie unter Endpunkt-URL des Webhooks die Webhook-URL ein, die mit „https://“ beginnt.
  6. Notieren Sie sich den clientToken-Wert. Sie benötigen ihn, um überprüfen zu können, ob eingehende Nachrichten von Google stammen.

  7. Konfiguriere deinen 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 sendet.

    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 den Webhook überprüft, 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. Decodieren Sie die RBM-Nutzlast mit Base64 im message.body-Element der Anfrage.
  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 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

Die Rückgabe von einem anderen Wert als 200 OK von einem Webhook gilt als Zustellungsfehler.

Entwickler müssen darauf achten, dass beim Senden von Nachrichten in hohen Frequenzen hohe Webhook-Benachrichtigungen generiert werden. Außerdem müssen sie ihren Code so gestalten, dass sie Benachrichtigungen in der erwarteten Häufigkeit empfangen 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. Dabei sollten Sie unter anderem Folgendes 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.

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. Danach wird die Nachricht verworfen.

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 Agents werden während des Backoff-Zeitraums einer fehlgeschlagenen Nachricht aufgerufen. Da fehlerhafte 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 und den entsprechenden Code entsprechend verstehen – so weit wie möglich, Nachrichten annehmen und zur Verarbeitung in die Warteschlange stellen, um die Chance 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.