Webhooks

Ein Webhook ist eine vom Partner angegebene URL, an die die RCS for Business-Plattform Nachrichten und Ereignissesendet. 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. Nachdem Sie Ihren Webhook konfiguriert haben, können Sie Nachrichten und Ereignisse empfangen.

Warnung: RCS for Business stellt Nachrichten für einen Partner in eine Warteschlange. Wenn der Webhook eines Agents fehlschlägt (keine Antwort vom Typ „200“ zurückgibt), kann sich das auf die Zustellung der Webhooks aller anderen Agents im selben Partnerkonto auswirken. Weitere Informationen finden Sie unter Auswirkungen von Webhooks auf Agent-Ebene.

Partner- und Agent-Webhooks

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

• Ihr Partner-Webhook gilt für alle Agents, die Sie verwalten. Wenn sich Ihre Agents ähnlich verhalten oder Sie nur einen Agent haben, verwenden Sie den Partner-Webhook.
• Agent-Webhooks gelten für einzelne Agents. Wenn Sie mehrere Agents mit unterschiedlichem Verhalten verwenden, können Sie für jeden Agent einen anderen Webhook festlegen.

Wenn Sie sowohl einen Partner- 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.

Agent-Webhook konfigurieren

**Hinweis**: Informationen zum Erstellen einer Webhook-Integration mit der RBM Management API finden Sie in der Dokumentation Webhook-Integration erstellen.

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

1. Öffnen Sie die RCS for Business Developer Console und melden Sie sich mit Ihrem Google-Konto für RCS for Business-Partner an.
2. Klicken Sie auf Ihren Agent.
3. Klicken Sie auf Integrations.
4. Klicken Sie im Bereich Webhook auf Konfigurieren.
   1. Geben Sie unter Webhook-Endpunkt Ihre Webhook-URL ein, die mit "https://" beginnt.
   2. Geben Sie unter Client-Token den Wert für clientToken an. Sie benötigen ihn, um zu prüfen , ob die Nachrichten, die Sie erhalten, von Google stammen.

5. Konfigurieren Sie Ihren Webhook so, dass er eine POST-Anfrage mit dem angegebenen Parameter clientToken akzeptiert und eine Antwort vom Typ 200 OK 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"
   }
   

   Dann sollte Ihr Webhook den Wert für clientToken bestätigen und, falls clientToken korrekt ist, eine Antwort vom Typ 200 OK mit 1234567890 als Antworttext zurückgeben:

   // clientToken from Configure
   const myClientToken = "SJENCPGJESMGUFPY";
   
   // Example endpoint
   app.post("/rbm-webhook", (req, res) => {
     // Use the X-Goog-Webhook-Type header to route requests
     const webhookType = req.header('X-Goog-Webhook-Type');
   
     if (webhookType === 'verification') {
       const msg = req.body;
       if (msg.clientToken === myClientToken) {
           res.status(200).send(msg.secret);
           return;
       }
     }
     res.send(400);
     // handle other webhook types
   });
   

6. Klicken Sie in der Developer Console auf Bestätigen. Wenn RCS for Business Ihren Webhook bestätigt hat, wird das Dialogfeld geschlossen.

Anfragetypen identifizieren

Verwenden Sie den Header X-Goog-Webhook-Type, um den Anfragetyp für alle Anfragen zu identifizieren, die an Ihren Webhook gesendet werden.

Der Header kann die folgenden Werte haben:

• verification: Wird für die erste Endpunktbestätigung verwendet.
• message_callback: Wird für nachrichtenbezogene Ereignisse verwendet, z. B. für Benachrichtigungen über die Eingabe oder Zustellung und für eingehende Nachrichten von Nutzern.
• agent_callback: Wird für agentspezifische administrative Ereignisse verwendet, z. B. für Änderungen des Startstatus des Agents.

Eingehende Nachrichten bestätigen

Da Webhooks Nachrichten von jedem Absender empfangen können, sollten Sie prüfen, ob Google die eingehenden Nachrichten gesendet hat, bevor Sie den Inhalt der Nachrichten verarbeiten.

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

1. Extrahieren Sie den Header X-Goog-Signature der Nachricht. Dies ist eine gehashte, base64-codierte Kopie der Nutzlast des Nachrichtentextes.
2. Decodieren Sie die RCS for Business-Nutzlast im Element message.body der Anfrage mit Base64.
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 codieren Sie das Ergebnis mit Base64.
4. Vergleichen Sie den X-Goog-Signature-Hash mit dem von Ihnen erstellten Hash.
   • Wenn die Hashes übereinstimmen, haben Sie bestätigt, dass Google die Nachricht gesendet hat.

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

     Wenn Ihr Hashing-Prozess korrekt funktioniert und Sie eine Nachricht erhalten, von der Sie glauben, dass sie Ihnen auf betrügerische Weise 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
    const headerHash = req.header('X-Goog-Signature');
    const userEventString = Buffer.from(requestBody.message.data, 'base64');
    const hmac = crypto.createHmac('sha512', myClientToken);
    const genHash = hmac.update(userEventString).digest('base64');

    if (headerHash === genHash) {
      const userEvent = JSON.parse(userEventString);
      const webhookType = req.header('X-Goog-Webhook-Type');

      // Route based on the header type
      if (webhookType === 'message_callback') {
        handleMessage(userEvent);
      } else if (webhookType === 'agent_callback') {
        handleAgentEvent(userEvent);
      }
    } else {
      console.log('Hash mismatch - ignoring message');
      res.sendStatus(401);
      return;
    }
  }

  res.sendStatus(200);
  

Nachrichtenverarbeitung

Wenn ein Webhook etwas anderes als 200 OK zurückgibt, gilt das als Zustellungsfehler.

Entwickler müssen beachten, dass beim Senden von Nachrichten mit hoher Geschwindigkeit auch Webhook-Benachrichtigungen mit hoher Geschwindigkeit generiert werden. Sie müssen ihren Code so gestalten, dass er Benachrichtigungen mit der erwarteten Geschwindigkeit verarbeiten kann. Entwickler müssen Situationen berücksichtigen, die zu Fehlerantworten führen können, z. B. 500-Antworten von ihrem Webcontainer, Zeitüberschreitungen oder Upstream-Fehler. Dabei sollten sie Folgendes beachten:

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

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

Es ist wichtig, das RBM-Ereignis nicht im Webhook selbst zu verarbeiten. Jeder Fehler oder jede Verzögerung bei der Verarbeitung kann sich auf den Rückgabecode des Webhooks auswirken:

Verhalten bei Zustellungsfehlern

Wenn Ihr Webhook etwas anderes als den Status 200 OK zurückgibt, verwendet die RCS for Business-Plattform einen Backoff- und Wiederholungsmechanismus, um die Daten noch einmal zu senden. Das bedeutet, dass das System die Verzögerung zwischen den einzelnen Zustellungsversuchen schrittweise erhöht, 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 eine Warteschlange. 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 Agents den Partner erreichen.

Mehrere unbestätigte Nachrichten können zu einem massiven Anstieg der Wiederholungsereignisse führen. Wenn ein Agent beispielsweise 1.600 Zustellungsbestätigungen nicht bestätigt und die Wiederholungsfrequenz 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 = etwa 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

Folgen Sie diesen Best Practices, um die Zuverlässigkeit Ihres Produktionsdatenverkehrs zu gewährleisten und Warteschlangenblockierungen 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 Antwort vom Typ 200 OK zurückgeben.
• Verarbeitung entkoppeln: Verwenden Sie separate Hintergrundprozesse, um die Nachrichtenlogik aus der lokalen Warteschlange zu verarbeiten.
• Test-Agents überwachen: Behandeln Sie Entwicklungs-Agents wie Produktions-Agents, da sie bei einem Fehler auch die gemeinsame Partner-Warteschlange blockieren können.
• Separate Konten für Tests: Verwenden Sie möglichst ein Entwicklerkonto für Produktions-Agents und ein separates Entwicklerkonto für Test-Agents.
• Google-Traffic bestätigen: Verwenden Sie Reverse-DNS oder den X-Goog-Signature Header anstelle einer statischen Zulassungsliste für IP-Adressen, da Google dynamische Anycast-IP-Adressen verwendet. Weitere Informationen zur manuellen Bestätigung und zur Identifizierung von Google-IP-Bereichen finden Sie in der Dokumentation Google-Anfragen bestätigen und insbesondere in den JSON-Dateien für Fetcher, die vom Nutzer ausgelöst wurden und Fetcher, die von Google ausgelöst wurden.

Nächste Schritte

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