Webhooks

Ein Webhook ist eine vom Partner angegebene URL, an die die RCS for Business-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 Sie möchten, dass Nachrichten für einen bestimmten KI-Agenten an einem anderen Webhook eingehen, legen Sie einen Agent-Webhook fest.

Öffnen Sie die Business Communications Developer Console und melden Sie sich mit Ihrem Google-Konto für RCS for Business-Partner an.
Klicken Sie auf den Agent.
Klicken Sie auf Integrations (Integrationen).
Klicken Sie für Webhook auf Konfigurieren.
Geben Sie unter Webhook-Endpunkt-URL Ihre Webhook-URL ein, die mit „https://“ beginnt.
Notieren Sie sich den Wert von clientToken. Sie benötigen sie, um zu bestätigen, dass Nachrichten, die Sie erhalten, von Google stammen.
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);
});
```
Klicken Sie in der Entwicklerkonsole auf Bestätigen. Wenn Ihr Webhook von RCS for Business bestätigt wird, wird das Dialogfeld geschlossen.

Eingehende Nachrichten überprüfen

Da Webhooks Nachrichten von jedem Absender 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:

Extrahieren Sie den X-Goog-Signature-Header der Nachricht. Dies ist eine gehashte, base64-codierte Kopie der Nutzlast des Nachrichtentexts.
Base64-decodieren Sie die RCS for Business-Nutzlast im Element message.body der Anfrage.
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.
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, funktionierenden 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 er Benachrichtigungen mit der erwarteten Rate verarbeiten kann. 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

Wenn Ihr Webhook einen anderen Status als 200 OK zurückgibt, verwendet die RCS for Business-Plattform einen Backoff- und Wiederholungsmechanismus, um die Daten noch einmal zu senden. Das System erhöht also die Verzögerung zwischen den einzelnen Zustellversuchen schrittweise, bis schließlich eine maximale Häufigkeit von einem Wiederholungsversuch alle 10 Minuten für jede ausstehende Nachricht erreicht wird. Der Wiederholungszyklus wird sieben Tage lang fortgesetzt. Danach wird die Nachricht endgültig gelöscht.

Auswirkungen von Webhooks auf Agent-Ebene

RCS for Business stellt Nachrichten für einen Partner in einer Warteschlange an. Alle Agents in einem Partnerkonto verwenden dieselbe Warteschlange. Daher kann ein Fehler in einem Webhook die gesamte Warteschlange blockieren und verhindern, dass Nutzerereignisse für alle Kundenservicemitarbeiter den Partner erreichen.

Mehrere unbestätigte Nachrichten können zu einem massiven Anstieg der Wiederholungsereignisse führen. Wenn ein Agent beispielsweise 1.600 Zustellbestätigungen nicht bestätigt und die Häufigkeit der Wiederholungsversuche das 10-Minuten-Limit erreicht, können etwa 230.000 potenzielle Fehler pro Tag auftreten:

1.600 Nachrichten × 6 Wiederholungsversuche pro Stunde × 24 Stunden pro Tag = ca. 230.000 Fehler pro Tag

Diese Anzahl von Wiederholungsversuchen kann die gemeinsame Pub/Sub-Warteschlange blockieren und zu erheblichen Verzögerungen beim Empfang von Nutzerereignissen für alle Kampagnen eines Partners führen.

Best Practices

Beachten Sie die folgenden Best Practices, um die Zuverlässigkeit Ihres Produktionsverkehrs zu gewährleisten und Warteschlangenblockaden zu vermeiden:

Sofort „200 OK“ zurückgeben: Der Webhook sollte die Nachricht empfangen, in einer lokalen Warteschlange speichern und innerhalb von fünf Sekunden eine 200 OK-Antwort zurückgeben.
Verarbeitung entkoppeln: Verwenden Sie separate Hintergrund-Worker, um die Nachrichtenlogik aus der lokalen Warteschlange zu verarbeiten.
Test-Agents überwachen: Behandeln Sie Entwicklungs-Agents wie Produktions-Agents, da sie die gemeinsame Partnerwarteschlange blockieren können, wenn sie fehlschlagen.
Dedizierte Konten für Tests: Verwenden Sie vorzugsweise ein Entwicklerkonto für Produktions-Agents und ein dediziertes Entwicklerkonto für Test-Agents.
Google-Traffic überprüfen: Verwenden Sie Reverse DNS oder den X-Goog-Signature-Header anstelle von Allowlisting mit festen IP-Adressen, da Google dynamische Anycast-IPs verwendet. Weitere Informationen zur manuellen Bestätigung und zum Identifizieren von Google-IP-Bereichen finden Sie in der Dokumentation Google-Anfragen bestätigen und insbesondere in den JSON-Dateien für vom Nutzer ausgelöste Fetcher und vom Nutzer ausgelöste Google-Fetcher.

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